« 发布支持旧版本软件包的错误修复 集成指南 »
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. Elasticsearch 实例

      • 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*
    • 必需 - 选项为必需
    • 显示用户 - 不要隐藏配置选项（折叠菜单）
    • 标题 - 人类可读的变量名称
    • 描述 - 变量描述（可能包含一些详细信息）
    • 类型 - 字段类型（根据参考：文本、密码、布尔值、整数）
    • 多值 - 该字段具有多个值。

  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 字段。如果是，只需将它们替换为更高效的字段。

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