更新的版本现已推出。有关最新信息，请参阅当前发行版文档。
« 拉取请求审查指南 为文档做贡献 »
Elastic 文档 ›Beats 开发者指南 [8.14]

对 Beats 做出贡献

编辑

对 Beats 做出贡献编辑

如果您有错误修复或新功能想要贡献，请先在论坛上开启一个主题。可能已经有人在做这件事了，或者在您实施更改之前，您应该先了解一下具体的问题。

我们很乐意与贡献者合作，使他们的代码被接受。解决一个问题有很多方法，在编写太多代码之前，找到最好的方法非常重要。提交代码后，请查看Elastic 贡献者计划，您可以在这里为您的贡献赢得积分和奖励。

向任何 Elastic 存储库贡献代码的过程都是类似的。

贡献步骤编辑

  1. 请确保您已签署我们的贡献者许可协议。我们不要求您将版权转让给我们，而是要求您授权我们无限制地分发您的代码。为了向用户保证代码的来源和持续存在，我们要求所有贡献者都签署此协议。您只需签署一次 CLA。
  2. 发送拉取请求！将您的更改推送到您的存储库分支，并使用我们的拉取请求指南提交拉取请求。新的 PR 会进入主分支。Beats 核心团队会在必要时将您的 PR 向后移植。

在拉取请求中，描述您的更改内容，并提及与拉取请求相关的任何错误/问题。同时，请在CHANGELOG.next.asciidoc中添加一个更改日志条目。

设置开发环境编辑

Beats 是 Go 程序，所以请安装用于 Beats 开发的Go 1.21.12 版本。

安装 Go后，设置GOPATH环境变量，使其指向您的工作区位置，并确保$GOPATH/bin位于您的 PATH 中。

一种确定性地安装正确 Go 版本以使用 Beats 的方法是使用GVM Go 版本管理器。对于 Mac 用户来说，示例如下：

gvm use 1.21.12
eval $(gvm 1.21.12)

然后，您可以克隆 Beats git 存储库

mkdir -p ${GOPATH}/src/github.com/elastic
git clone https://github.com/elastic/beats ${GOPATH}/src/github.com/elastic/beats

如果您有多个 go 路径，请使用${GOPATH%%:*}代替${GOPATH}。

Beats 开发人员主要使用Mage进行开发。您可以使用 make 目标安装 mage

make mage

然后，您可以使用 Mage 编译特定的 Beat。例如，对于 Filebeat

cd beats/filebeat
mage build

您可以使用以下命令列出所有可用的 mage 目标

mage -l

某些 Beat 可能有额外的开发要求，在这种情况下，您会在 Beat 目录中找到 CONTRIBUTING.md 文件。

我们在 Beats 存储库中使用EditorConfig文件来标准化不同编辑器如何处理文件中的空格、行尾和其他编码风格。大多数流行的编辑器都有一个用于 EditorConfig 的插件，我们强烈建议您安装它。

更新脚本编辑

Beats 使用各种基于 Python、make 和 mage 的脚本生成配置文件和文档。用于此目的的主要命令是

make update

每个 Beat 都有自己的update目标（对于make和mage），并且在存储库根目录中有一个主update。如果 PR 添加或删除了依赖项，请在根beats目录中运行make update。

另一个命令可以正确格式化 go 源文件并添加版权标头

make fmt

在提交 PR 之前，应该运行这两个命令。您可以使用make help查看所有可用的 make 目标。

这些命令具有以下依赖项

Python venv 模块包含在 Python 3 的标准库中。在 Debian/Ubuntu 系统上，还需要安装python3-venv包，其中包含额外的支持脚本

sudo apt-get install python3-venv

选择构建目标编辑

Beats 是使用make release目标构建的。默认情况下，make 将从有限数量的预设构建目标中进行选择

  • darwin/amd64
  • darwin/arm64
  • linux/amd64
  • windows/amd64

您可以使用PLATFORMS环境变量更改构建目标。使用PLATFORMS变量设置的目标可以是 GOOS 值，也可以是 GOOS/arch 对。例如，linux和linux/amd64都是有效的目标。您可以选择多个目标，并且PLATFORMS列表是用空格分隔的，例如，darwin windows将在所有受支持的 darwin 和 windows 架构上构建。此外，您还可以通过在给定目标前面添加+或-来添加或删除构建目标列表。例如：+bsd或-darwin。

您可以使用go tool dist list查找受支持的构建目标的完整列表。

代码检查编辑

Beats 使用golangci-lint。您可以对您的更改运行预先配置的代码检查器

mage llc

llc代表Lint Last Change，它包括在最后一次提交（如果您在main分支上）或在您的功能分支与main分支之间的差异中更改的所有 Go 文件。

预计有时会要求贡献者修复与其贡献无关的代码检查器问题，因为代码检查器的引入时间晚于某些文件的更改。

您还可以对单个包运行代码检查器，例如 filbeat 命令包

golangci-lint run ./filebeat/cmd/...

测试编辑

您可以使用以下命令运行整个测试套件

make testsuite

运行测试套件有以下要求

  • Python >= 3.7
  • Docker >= 1.12
  • Docker-compose >= 1.11

有关更多详细信息，请参阅测试指南。

文档编辑

每个 Beat 的主要文档位于<beatname>/docs下，并且基于AsciiDoc。Beats 文档还广泛使用了条件和内容重用，以确保一致性和准确性。在为文档做贡献之前，请阅读以下资源

依赖项编辑

为了创建 Beats，我们依赖于 Golang 库和其他外部工具。

其他依赖项编辑

除了 Go 库之外，我们还使用开发工具来生成输入和处理器的解析器。

运行go generate需要以下软件包

Auditbeat编辑
  • FlatBuffers >= 1.9
Filebeat编辑
  • Graphviz >= 2.43.0
  • Ragel >= 6.10

更改日志编辑

要及时了解官方 Beats 的变化，社区开发者可以关注这里的开发者更改日志。

« 拉取请求审查指南 为文档做贡献 »