快速入门：示例集成

这是一个快速指南，介绍如何构建自己的集成包并将其上传到 Kibana。

按照以下步骤创建一个名为 sample 的集成包，然后添加一个 logs 数据集。 相同的过程可用于 metrics 数据集，但是，对于您的第一个集成包，logs 稍微简单一些，因为不需要自定义输入。

• 先决条件
• 步骤 1：创建包
• 步骤 2：将包上传到 Kibana
• 步骤 3：创建数据集
• 步骤 4：添加处理
• 步骤 5：发布新版本
• 步骤 6：摄取数据
• 下一步是什么？

您需要满足一些要求才能运行本教程

• 在您的机器上安装了 elastic-package。 这是一个命令行工具，用 Go 编写，用于开发 Elastic 包。 它可以帮助您检查、格式化、测试、构建和推广您的包。 设置说明可以在 elastic-package 仓库的 readme 中找到。
• 您可以在 GitHub 仓库 上传您的集成包。
• 在您的机器上设置并运行 Docker。

1. 首先，从 Git 仓库中，运行 elastic-package create package 命令。 这将启动一个向导，提示您输入一些详细信息，然后构建一个包含所有必要部分的空包

    elastic-package create package 

2. 按如下方式响应提示

   • 包类型：integration
   • 包名：sample
   • 版本：0.0.1
   • 许可证：Elastic-2.0
   • 包标题：My sample package
   • 描述：My first integrations package to collect logs（我的第一个集成包，用于收集日志）
   • 类别：custom
   • Kibana 版本约束：^8.12.2
   • 所需 Elastic 订阅：basic
   • Github 所有者：<您的 github 用户名>
   • 所有者类型：elastic

3. 输入详细信息后，该命令应返回确认您的包已创建的消息。

4. 更改到新的 sample 包目录中。

    cd sample 

5. 验证新的集成包是否已正确创建。

   1. 检查包的 linting 规则

       elastic-package lint 

   2. 格式化包以修复 linting

       elastic-package format 

   3. 从包资产构建一个 .zip 文件

       elastic-package build 

   4. 如果您愿意，您也可以将前三个命令作为一个批处理运行

       elastic-package check 

1. 要测试您的包是否可以安装到 Kibana 中，需要启动一个集群。 为此步骤，您需要运行 Docker 设置。 运行以下命令

    elastic-package stack up --version=8.12.2 -v 

   这会启动一个具有 Elastic Stack 的 8.12.2 版本的集群。 可以在浏览器中通过 https://localhost:5601 访问该集群，用户名为 elastic，密码为 changeme。

   注意

   • 如果要更新到最新的 Elastic Stack 版本，请运行 elastic-package stack update --version=8.12.2 -v。
   • 您还可以将包直接安装到现有集群中进行测试。 install 命令的步骤和自定义选项在此 How To guide（操作指南）中进行了描述，位于 elastic-package 仓库中。

2. 集群设置完成后，打开第二个终端窗口并运行以下命令以安装您的包

    elastic-package install 

3. 命令运行后，检查您的新包是否出现在 Kibana 的 Management > Integrations > Installed integrations（管理 > 集成 > 已安装的集成）下。

   

您现在已经构建了一个集成包，但它不包含任何资产。 为了开始收集日志，您需要创建一个数据集，并为其创建 Elasticsearch 映射和摄取管道。 如果您希望能够通过托管的 Elastic Agent 收集数据，您还需要添加一个代理策略模板。

1. 创建一个新的数据集

    elastic-package create data-stream 

2. 出现提示时，提供以下详细信息

   • 数据流名称：log

   • 数据流标题：My log lines（我的日志行）

   • 类型：logs

     该命令在 /data_stream/log 目录中创建所需的数据。 如果您选择 log 作为数据流名称，则数据集称为 sample.log，最终创建的数据流将是 logs-sample.log-default，例如。

3. 为了不必担心映射，您可以拉取所有 Elastic Common Schema (ECS) 字段。为此，在根目录下创建文件 _dev/build/build.yml 并添加以下内容

   dependencies:
     ecs:
       reference: git@v8.6.0
       import_mappings: true
   

4. 最好始终重新检查以确保您的包仍然构建并且工作正常。

    elastic-package check 

5. 重新安装您的包。

    elastic-package install 

   这会重新安装该包并为 logs-sample.log-* 创建映射模板。 如果需要，您还可以在 data_stream/log/fields/fields.yml 下添加您自己的映射。

您现在已经可以将日志文件发送到 logs-sample.log-default，但不会进行任何处理。 因此，让我们创建一个示例日志文件。

1. 创建一个文件 test-sample.log，其中包含以下内容，并将其保存在您本地机器上的任何位置。

    2024-04-21T13:44:56.657+0100 INFO Hello world 2024-04-21T13:45:56.657+0100 INFO This is a nice day
   2024-04-21T13:46:56.657+0100 INFO I am working on stuff
   

   日志文件的每一行都将由 Elastic Agent 作为文档发送，该文档的 message 字段包含日志行。 您将设置 dissect 处理器，将日志行分解为 @timestamp、log.level 和 message。

2. 接下来，测试您的摄取管道。 在 Kibana 中，导航到 Management > Dev Tools（管理 > 开发工具）并运行 Simulate pipeline API（模拟管道 API）

    POST /_ingest/pipeline/_simulate {
     "pipeline" :
     {
       "description": "logs-sample.log",
       "processors": [
         {
           "dissect" : {
             "field" : "message",
             "pattern" : "%{@timestamp} %{log.level} %{message}"
           }
         }
       ]
     },
     "docs": [
       {
         "_index": "index",
         "_id": "id",
         "_source": {
           "message": "2023-02-21T13:46:56.657+0100 INFO I am working on stuff"
         }
       }
     ]
   }
   

   这将返回

    {   "docs": [
       {
         "doc": {
           "_index": "index",
           "_version": "-3",
           "_id": "id",
           "_source": {
             "@timestamp": "2023-02-21T13:46:56.657+0100",
             "message": "I am working on stuff",
             "log": {
               "level": "INFO"
             }
           },
           "_ingest": {
             "timestamp": "2024-04-30T17:51:22.16442471Z"
           }
         }
       }
     ]
   }
   

3. 现在您已经确认摄取管道正在工作，请通过修改 data_stream/log/elasticsearch/ingest_pipline/default.yml 将其添加到您的数据集

    description: Pipeline for processing sample logs processors:
   - dissect:
       field: message
       pattern: "%{@timestamp} %{log.level} %{message}"
   on_failure:
   - set:
       field: error.message
       value: '{{ _ingest.on_failure_message }}'
   

4. 现在再次运行 elastic-package check，然后使用 elastic-package install 重新上传该包。 这将安装您的新摄取管道。

5. 进行快速测试运行以测试新管道。 在 Dev tools（开发工具）控制台中，运行

    POST logs-sample.log-default/_doc {
     "message": "2023-02-21T13:46:56.657+0100 INFO I am working on stuff"
   }
   

   响应为

    {   "_index": ".ds-logs-sample.log-default-2024.04.30-000001",
     "_id": "BsUtMI8BQEniT9Md_TYh",
     "_version": 1,
     "result": "created",
     "_shards": {
       "total": 2,
       "successful": 1,
       "failed": 0
     },
     "_seq_no": 0,
     "_primary_term": 1
   }
   

6. 现在运行

    GET logs-sample.log-default/_search 

   响应为

    {   "took": 1,
     "timed_out": false,
     "_shards": {
       "total": 1,
       "successful": 1,
       "skipped": 0,
       "failed": 0
     },
     "hits": {
       "total": {
         "value": 1,
         "relation": "eq"
       },
       "max_score": 1,
       "hits": [
         {
           "_index": ".ds-logs-sample.log-default-2024.04.30-000001",
           "_id": "BsUtMI8BQEniT9Md_TYh",
           "_score": 1,
           "_source": {
             "@timestamp": "2023-02-21T13:46:56.657+0100",
             "message": "I am working on stuff",
             "event": {
               "agent_id_status": "missing",
               "ingested": "2024-04-30T18:04:31Z"
             },
             "log": {
               "level": "INFO"
             }
           }
         }
       ]
     }
   }
   

现在您可以看到已分解的消息记录在案，您就可以摄取数据了。

1. 自从您最初的 0.0.1 版本的包以来，已经进行了许多修改。 要构建新的包版本，请打开 sample/manifest.yml 文件并将包版本更改为 0.2.0

    format_version: 3.1.3 name: sample
   title: "My sample package"
   version: 0.2.0
   

2. 您还需要向您的 sample/changelog.yml 文件添加一个条目。 确保将新条目添加到文件的顶部

    - version: "0.2.0" changes:
     - description: Added sample log processing pipeline
       type: enhancement
       link: http://fake-link
   

   注意

   您还可以使用 elastic-package changelog 命令自动更新 changelog 文件。

3. 再次运行 elastic-package check，然后运行 elastic-package install 命令。

   该包的 0.1.0 版本已更新为 0.2.0 版本。 一次只能安装一个版本的包，但是，按照这些步骤，可以随着时间的推移推出不同版本的包。

在开发集成时，应使用以下版本控制准则

• 补丁版本 (x.y.Z)：用于向后兼容的错误修复
• 次要版本 (x.Y.z)：用于向后兼容的新功能
• 主要版本 (X.y.z)：用于破坏向后兼容性的更改

您可以通过两种不同的方式摄取数据，使用独立的 Elastic Agent 或由 Fleet 管理的 Elastic Agent。 对于此示例，您可以使用独立的 Elastic Agent，因为它不需要对集成包进行任何其他更改。

1. 将 Elastic Agent 安装包下载 到您的机器。

2. 下载 Elastic Agent 包，解压它，然后更改到该包目录中。 您可以在 Install standalone Elastic Agents（安装独立的 Elastic Agent）中找到每个可用平台的步骤。

   您还可以直接从 Elastic Agent 下载站点 下载一个包。

3. 在 Elastic Agent 包目录中，打开 elastic-agent.yml 配置文件进行编辑。

4. 将 elastic-agent.yml 的内容替换为以下内容

    inputs:   - type: logfile
       streams:
         - data_stream:
             # This must be aligned with the dataset name given
             dataset: test-sample.log
           paths:
             # Path to your log file
             - /<PATH-TO-LOG-FILE>/test-sample.log
   
   outputs:
     default:
       type: elasticsearch
       hosts: ["https://127.0.0.1:9200"]
       username: "elastic"
       password: "changeme"
       ssl.verification_mode: none
   

   其中

   • dataset 设置为与您创建的 test-sample.log 文件匹配。
   • <PATH-TO-LOG-FILE> 是您创建的 test-sample.log 文件的完整路径。

5. 运行 Elastic Agent

    sudo ./elastic-agent -e 

   这将获取日志文件，将其发送到 Elasticsearch，并使用摄取管道对其进行处理。

6. 确认您的日志文件正在按预期摄取

   1. 在 Kibana 中，打开 Discover（发现）。

   2. 在搜索字段中，输入 log.file.path.text : *。 搜索应返回几个日志条目。

   3. 将鼠标悬停在条目上并单击 Enter 以查看单元格内容。

      

您现在拥有自己的集成包，您可以更新新功能并将其发送到 Elastic Stack 或与他人共享。

在集成 Contributing Guide（贡献指南）中，您可以找到有关向集成添加其他资产（例如 Kibana 仪表板）的说明。

让其他人了解您的新集成

• 在 Elastic Community（Elastic 社区）中与 Elastic 一起推广您的集成。
• 在 Elastic’s Partner Portal（Elastic 合作伙伴门户网站）上注册为技术合作伙伴。