« 为支持旧软件包版本发布错误修复 集成指南 »
Elastic 文档 ›集成开发人员指南 ›开发者工作流程

从 Beats 模块导入集成

编辑

从 Beats 模块导入集成编辑

导入过程主要使用 import-beats 脚本。如果您对它的内部工作原理感兴趣，可以随意查看该脚本的 README。

  1. 在 integrations 中创建一个问题以跟踪集成的持续进展（特别是手动更改）。

    专注于您要集成的特定产品（例如 MySQL、ActiveMQ）。使用此问题来提及已应用的每个手动更改。它将有助于调整 import-beats 脚本并审查集成。

  2. 准备开发环境

    1. 克隆/刷新以下存储库

    2. 克隆/刷新 Elastic 集成以始终使用最新版本的脚本

    3. 确保您已安装 mage 工具

      $ go get -u -d github.com/magefile/mage

  3. 使用 elastic-package stack up -v -d 命令启动所需依赖项

    1. Elasticseach 实例

      • Kibana 的依赖项

    2. Kibana 实例

      • 用于迁移仪表板，如果不可用，您可以跳过生成（SKIP_KIBANA=true）

        提示。elastic-package 速查表可在此处获得 此处。

  4. 在 integrations 存储库中为集成创建一个新分支（从主分支分支）。

  5. 运行命令：mage ImportBeats 以启动导入过程（请注意，导入脚本假设在步骤 2 中签出的项目位于 +../{project-name}+）。

    运行 import-beats 脚本的结果是目录，其中包含更新的集成。

    完成需要一段时间，但控制台输出应经常更新以跟踪进度。命令应以退出代码 0 结束。如果它没有结束，请打开一个问题。

    生成的包默认存储在 packages 目录中。通常，导入过程会更新所有集成，因此如果您注意到对多个集成（包括您当前正在处理的集成）的更新，请不要感到意外（例如 packages/foobarbaz）。您可以提交这些更改或稍后再提交。

    如果您想选择一组包，请设置环境变量 PACKAGES（逗号分隔列表）

    $ PACKAGES=aws,cisco mage ImportBeats

微调集成编辑

import-beats 脚本完成了大部分迁移工作，但有些任务需要开发人员的参与。

您的集成可能缺少屏幕截图或图标，这是向 Beats/Kibana 存储库添加缺失资源并重新导入集成（幂等）的好时机。

清单编辑

建议按照清单上的操作项顺序执行，以防止贡献者重复某些操作（修复已经修复的内容，因为脚本已经覆盖了部分内容）。

  1. 如果缺少，请添加图标。

    集成图标在 Kibana 的不同地方显示，因此最好定义自定义图标以使 UI 更易于导航。

    由于 import-beats 脚本在 Kibana 和 EUI 存储库中查找图标，因此请以与教程资源相同的方式向第一个存储库添加一个图标（Kibana 目录：src/legacy/core_plugins/kibana/public/home/tutorial_resources/logos/）。

  2. 如果缺少，请添加屏幕截图。

    Kibana 集成管理器显示与集成相关的屏幕截图。屏幕截图展示了 Kibana 仪表板，用于可视化指标/日志数据。

    import-beats 脚本查找 _meta/docs.asciidoc 中提到的屏幕截图的引用，并将图像文件从 Beats 目录复制

    • metricbeat/docs/images
    • filebeat/docs/images

  3. 改进/更正产品名称的拼写。

    产品名称的正确拼写可以带来更好的印象。 import-beats 脚本使用 fields.yml 文件作为正确拼写（title 属性）的来源，例如 Mysql - MySQL、Nginx - NGINX、Aws - AWS。

    请记住，此步骤需要重新导入包内容。

  4. 为集成编写 README 模板文件。

    README 模板用于呈现最终的 README 文件，包括导出的字段。模板应放置在 package/<integration-name>/_dev/build/docs/README.md 中。如果目录不存在，请创建它。

    查看 MySQL 文档模板以了解如何使用模板函数（例如 {{fields "data-stream-name"}}）。如果指标和日志都使用相同的 数据流名称，请在模板中添加 -metrics 和 -logs。例如，elb 是日志的数据流，也是指标的数据流。在 README.md 模板中，{{fields "elb_logs"}} 和 {{fields "elb_metrics"}} 用于将它们分开。

  5. 查看字段文件和文档中的导出字段。

    此操作项的目标是验证生成的工件是否正确。

    包中的字段文件（package-fields.yml、fields.yml 和 ecs.yml）是从原始 fields.yml 文件（可能包含 ECS 架构字段）和 fields.epr.yml（定义摄取管道中使用的其他一些字段）创建的。原始源可能存在拼写错误、描述不当或缺少字段定义。所有现有文件中的字段总和应该只包含实际使用的字段，例如，并非所有现有的 ECS 字段。

    摄取管道可能使用从 ECS 中抽象出的字段，但未在 fields.yml 中提及。集成应该包含这些字段并对其进行文档化。

    集成包的字段分为以下三个文件

    • ecs.yml：此特定数据流使用的符合 ECS 的字段。
    • package-fields.yml：此特定数据流使用的包级字段，该字段不存在于 <integration-package-name>.<data-stream-name> 下。
    • fields.yml：特定于此特定数据流且不符合 ECS 的数据集级字段。

    请参阅 PR https://github.com/elastic/beats/pull/17895，了解如何使用 fields.epr.yml 文件将它们添加到 Beats（例如 event.code、event.provider）。

  6. Metricbeat：添加缺失的配置选项。

    import-beats 脚本从 Metricbeat 模块的 _meta 目录中提取配置选项。它分析配置文件，并根据启用的指标集（未注释）选择选项。如果您发现您的包的清单文件中缺少一些配置选项，只需创建包含所有必需选项的 config.epr.yml 文件。

    示例 PR：https://github.com/elastic/beats/pull/17323

  7. 查看清单文件中的 标题 和 描述。

    标题和描述是在 Kibana UI 中可视化的字段。大多数用户将使用它们来查看如何使用产品的安装配置集成或如何使用高级配置选项。

  8. 压缩配置选项（变量）。

    目前，所有配置选项都由 import-beats 脚本在流级别设置（路径：data stream/<data-stream-name>/manifest.yml）。

    可能会发生在不同数据流中，其中一些只是重复项或关注相同设置，这将始终相同（例如 MySQL 用户名、密码）。请记住，两个数据流可能具有相同的配置选项，但值不同（例如 period、paths），因此无法压缩。

    总而言之，压缩消除了用户需要多次设置相同配置选项（每个数据流一个）的必要性。

  9. 定义所有变量属性。

    变量属性在 Kibana UI 中自定义配置选项的可视化。确保它们在所有清单文件中定义。

        vars:
      - name: paths
        required: true
        show_user: true
        title: Access log paths
        description: Paths to the nginx access log file.
        type: text
        multi: true
        default:
          - /var/log/nginx/access.log*
    • required - 选项是必需的
    • show_user - 不要隐藏配置选项（折叠菜单）
    • title - 人类可读的变量名称
    • description - 变量描述（可能包含一些详细信息）
    • type - 字段类型（根据引用：text、password、bool、integer）
    • multi - 该字段具有多个值。

  10. 查看流配置。

    由于模板引擎从标准 Golang 模板引擎更改为 handlebars，因此可能难以自动转换 Filebeat 输入配置（嵌套变量、多种表示形式、条件、循环）。请查看输出流配置并识别潜在的错误。

  11. 使用示例事件更新文档模板。

    代理收集的事件与原始的、Metricbeat 和 Filebeat 事件略有不同。根据已经迁移的集成（例如 MySQL 集成）手动调整事件内容，或者在使用真实代理运行整个设置后复制它们。

  12. Kibana：使用 stream.data stream 字段而不是 event.data stream。

    使用 stream.data stream 而不是 event.data stream 还会使查询效率更高，因为这是一个 constant_keyword。确保包中的仪表板不使用 event.data stream 字段。如果是这样，只需将它们替换为更高效的字段。

« 为支持旧软件包版本发布错误修复 集成指南 »