›

快速入门：示例集成

编辑

快速入门：示例集成编辑

此快速入门专为熟悉 Elastic Stack 的用户设计。如果您不熟悉 Elastic，构建集成 提供了有关创建新集成的深入介绍。

本指南简要介绍了如何构建自己的集成包并将其上传到 Kibana。

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

先决条件编辑

您需要满足以下几个要求才能运行本教程

在您的机器上安装 elastic-package。这是一个用 Go 编写的命令行工具，用于开发 Elastic 包。它可以帮助您对包进行 lint、格式化、测试、构建和提升。在 elastic-package 存储库自述文件中可以找到安装说明。
您可以将集成包上传到的 GitHub 存储库。
在您的机器上安装并运行 Docker。

步骤 1：创建包编辑

首先，在 Git 存储库中，运行 elastic-package create package 命令。这将启动一个向导，提示您提供一些详细信息，然后构建一个包含所有必要部分的空包。
```
elastic-package create package
```
按如下方式回答提示
- 包类型：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 所有者：<your github name>
- 所有者类型：elastic
输入完详细信息后，该命令应返回一个确认消息，表明您的包已创建。
切换到新的 sample 包目录。
```
cd sample
```
验证新创建的集成包是否正确。
1. 检查包的 linting 规则
```
elastic-package lint
```
2. 格式化 pacakge 以修复 linting
```
elastic-package lint
```
3. 从包资产构建一个 .zip 文件
```
elastic-package build
```
4. 如果您愿意，也可以将前面三个命令作为一个批处理运行
```
elastic-package check
```

步骤 2：将包上传到 Kibana编辑

要测试您的包是否可以安装到 Kibana，需要启动一个集群。此步骤需要您拥有一个正在运行的 Docker 环境。运行以下命令
```
elastic-package stack up --version=8.12.2 -v
```
这将启动一个使用 Elastic Stack 8.12.2 版本的集群。您可以通过浏览器中的 https://127.0.0.1:5601 访问该集群，用户名为 elastic，密码为 changeme。
- 如果您想要更新到最新的 Elastic Stack 版本，请运行 elastic-package stack update --version=8.12.2 -v。
- 您也可以将包直接安装到现有集群中进行测试。install 命令的步骤和定制选项在 elastic-package 存储库中的使用说明指南中有描述。
集群设置完成后，打开第二个终端窗口并运行以下命令以安装您的包
```
elastic-package install
```
命令运行完成后，检查您的新包是否出现在 Kibana 的 管理 > 集成 > 已安装集成 中。

步骤 3：创建数据集编辑

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

创建新的数据集
```
elastic-package create data-stream
```
当系统提示时，提供以下详细信息
- 数据流名称：log
- 数据流标题：My log lines
- 类型：logs
  
  该命令将在 /data_stream/log 目录中创建所需的数据。如果您选择 log 作为数据流名称，数据集将被称为 sample.log，创建的最终数据流将以 logs-sample.log-default 为例。
为了不担心映射问题，您可以引入所有 Elastic Common Schema (ECS) 字段。为此，请在根目录下创建文件 _dev/build/build.yml，并添加以下内容
```
dependencies:
  ecs:
    reference: [email protected]
    import_mappings: true
```
始终建议您重新检查以确保您的包仍然可以构建并按预期工作。
```
elastic-package check
```
重新安装您的包。
```
elastic-package install
```
这将重新安装您的包，并为 logs-sample.log-* 创建映射模板。如果需要，您也可以在 data_stream/log/fields/fields.yml 下添加您自己的映射。

步骤 4：添加处理编辑

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

创建一个名为 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 作为包含日志行的消息字段的文档发送。您将设置 dissect 处理器，将日志行分解为 @timestamp、log.level 和 message。

接下来，测试您的摄取管道。在 Kibana 中导航到 管理 > 开发工具，并运行模拟管道 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"
        }
      }
    }
  ]
}

现在，您已确认摄取管道正常工作，请将其添加到您的数据集中，方法是修改 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 }}'

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

进行快速测试以测试新管道。在 开发工具 控制台中，运行

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
}

现在运行

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"
          }
        }
      }
    ]
  }
}

现在您可以看到分解后的消息文档，您已准备好摄取数据。

步骤 5：发布新版本编辑

自您创建包的初始版本 0.0.1 以来，已经进行了许多修改。要构建新的包版本，请打开 sample/manifest.yml 文件，并将包版本更改为 0.2.0
```
format_version: 3.1.3
name: sample
title: "My sample package"
version: 0.2.0
```
您还需要在 sample/changelog.yml 文件中添加一个条目。确保将新的条目添加到文件的顶部
```
- version: "0.2.0"
  changes:
    - description: Added sample log processing pipeline
      type: enhancement
      link: http://fake-link
```
您也可以使用 elastic-package changelog 命令自动更新 changelog 文件。
再次运行 elastic-package check，然后运行 elastic-package install 命令。

包的版本 0.1.0 已更新到版本 0.2.0。一次只能安装一个版本的包，但是，通过执行这些步骤，可以随着时间的推移逐步推出不同版本的包。

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

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

步骤 6：摄取数据编辑

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

要使用 Fleet 管理的 Elastic Agent 运行这些步骤，您只需要更新文件 data_stream/log/agent/stream/stream.yml.hbs 和 data_stream/log/manifest.yml 以提供正确的配置，您可以在 Fleet UI 中找到这些配置。

下载 Elastic Agent 安装包到您的机器上。
下载 Elastic Agent 包，将其解压缩，并切换到包目录。您可以在安装独立 Elastic Agent 中找到每个平台的步骤。

您也可以直接从 Elastic Agent 下载网站下载包。
在 Elastic Agent 包目录中，打开 elastic-agent.yml 配置文件进行编辑。

将 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 文件的完整路径。

运行 Elastic Agent
```
sudo ./elastic-agent -e
```
这将提取日志文件，将其发送到 Elasticsearch，并使用摄取管道对其进行处理。
确认您的日志文件按预期摄取
1. 在 Kibana 中，打开发现。
2. 在搜索字段中，输入 log.file.path.text : *。搜索应返回几个日志条目。
3. 将鼠标悬停在条目上，然后单击 Enter 以查看单元格内容。

接下来做什么？编辑

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

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

让其他人了解您的新集成

在 Elastic 社区中宣传您的集成，以 Elastic。
注册 Elastic 的合作伙伴门户作为技术合作伙伴。

« 定义构建集成 »