正在加载

构建集成技巧

本节为开发者提供一系列技巧，以改进他们正在开发的集成。它结合了提示、指南、建议和技巧。请将本节视为一份实时文档，未来可能会根据整个平台（Elastic Package Registry、Elastic Agent 和 Kibana）的业务或技术要求而发展。

elastic-package

elastic-package 是一个用 Go 编写的命令行工具，用于开发 Elastic 包。它可以帮助您检查、格式化、测试和构建您的包。这是开发集成的官方构建工具。请参阅快速入门部分，以快速上手并查看其功能。

如果您需要正确版本的 elastic-package 修订版（与 CI 使用的版本相同），该版本在 go.mod 中定义，请使用以下命令（在 Integrations 存储库中）

$ go build github.com/elastic/elastic-package
$ ./elastic-package help

新的集成

清单文件

  1. 将初始版本设置为 0.1.0。

    使用较低的版本（如 0.0.1）标记集成，意味着它处于非常早期的阶段，并且很可能根本无法工作。它可能只是部分开发。

  2. 为集成选择一个或两个类别。

    可用类别的列表位于 Package Registry 源代码中：https://github.com/elastic/package-registry/blob/1dd3e7c4956f7e34809bb87acae50b2a63cd7ad0/packages/package.go#L29-L55

  3. 确保 Kibana 的版本条件设置为 +^7.10.0+ 而不是 >=7.10.0。 否则，该软件包也将在 8.0.0 中，但我们今天不知道它是否真的与 >= 8.0.0 兼容。

    conditions:
  kibana.version: '^7.10.0'

  4. 设置正确的包所有者（Github 团队或个人帐户）

    团队的良好候选者：elastic/integrations, elastic/security-service-integrations

    相应地更新 .github/CODEOWNERS 文件。

所有集成

开发

  1. 当您正在开发集成并且想要将更改传播到包注册表时，首先重建包

    $ cd packages/apache
$ elastic-package build

    然后，重建并重新部署 Package Registry

    在 Integrations 存储库中执行以下命令非常重要。

    $ elastic-package stack up -v -d --services package-registry

    说明：重建并重新启动带有 Package Registry 的容器比使用挂载卷更快。

代码审查者

  1. Ping "Team:Integrations"。

    使用团队标签通知相关团队成员有关传入的拉取请求。

清单文件

  1. 配置选项的描述应尽可能简短。

    请记住只保留有关配置选项的有意义的信息。

    好的候选者：对产品配置的引用、接受的字符串值、解释。

    不好的候选者：从 A、B、C、D,…​ X、Y、Z 数据集中收集指标。

  2. 描述应具有可读性。

    尝试将诸如：收集 foo_Bar3 指标之类的句子改为收集 Foo Bar 指标。

  3. 描述应易于理解。

    简化句子，如果不需要，请勿提供有关输入的信息。

    不好的候选者：收集应用程序日志（日志输入）

    好的候选者：收集应用程序日志，收集应用程序的标准日志

  4. 字母大小写对于屏幕截图描述非常重要。

    这些描述在 Kibana UI 中可视化。 最好使它们干净且一致。

    不好的候选者：filebeat 在 ec2 机器上运行

    好的候选者：Filebeat 在 AWS EC2 机器上运行

  5. 如果包依赖于某些功能或字段，这些功能或字段仅在特定堆栈或 Beats 版本中可用，则应在包的 manifest.yml 中相应地调整 kibana.version 条件

    conditions:
   kibana.version: '^8.7.0'
    注意

    具有上述条件的包版本将仅在 Kibana 版本 >=8.7.0 中可用

    注意

    使用未发布的 Kibana 版本更改仪表板和可视化可能不安全，因为 Kibana 团队可能会对 Kibana 代码和潜在的数据模型进行更改。 无法保证您的更改在新的 Kibana 版本发布时不会被破坏。

CI

  1. 在本地运行 elastic-package check 和 elastic-package test。

    如果您想验证您的集成是否按预期工作，您可以执行与 CI 相同的步骤

    $ cd packages/apache
$ elastic-package check -v
$ elastic-package test -v

    请记住，elastic-package test 命令需要一个正在运行的实时集群和导出的环境变量。 可以使用 eval "$(elastic-package stack shellinit)" 设置环境变量。

字段

  1. 删除空字段文件。

    如果您注意到字段文件（例如，package-fields.yml）不包含任何字段定义或仅定义根，请随时将其删除。

    不好的候选者

    - name: mypackage.mydataset
  type: group
© . All rights reserved.