›

快速入门：示例集成

编辑

快速入门：示例集成

编辑

本快速入门指南面向熟悉 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
- 包标题：我的示例包
- 描述：我的第一个收集日志的集成包
- 类别：custom
- Kibana 版本约束：^8.12.2
- 所需的 Elastic 订阅：basic
- Github 拥有者：<您的 github 名称>
- 拥有者类型：elastic
输入详细信息后，命令应返回确认您的包已创建的消息。
切换到新的 sample 包目录。
```
cd sample
```
验证新的集成包是否已正确创建。
1. 检查包的 linting 规则
```
elastic-package lint
```
2. 格式化包以修复 linting
```
elastic-package format
```
3. 构建包资源的 .zip 文件
```
elastic-package build
```
4. 如果您愿意，也可以将前三个命令作为单个批处理运行
```
elastic-package check
```

步骤 2：将包上传到 Kibana

编辑

为了测试您的包是否可以安装到 Kibana，需要启动一个集群。此步骤需要您拥有一个正在运行的 Docker 设置。运行以下命令
```
elastic-package stack up --version=8.12.2 -v
```
这将启动一个包含 8.12.2 版本 Elastic Stack 的集群。您可以通过浏览器访问该集群 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 收集数据，则还需要添加一个 Agent 策略模板。

创建一个新的数据集
```
elastic-package create data-stream
```
出现提示时，提供以下详细信息
- 数据流名称：log
- 数据流标题：我的日志行
- 类型：logs
  
  该命令在 /data_stream/log 目录中创建所需的数据。如果您选择 log 作为数据流名称，则数据集称为 sample.log，最终创建的数据流将例如为 logs-sample.log-default。
为了不必担心映射，您可以引入所有 Elastic 通用模式 (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 作为包含包含日志行的 message 字段的文档来发送。您将设置 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 命令自动更新更改日志文件。
再次运行 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 的合作伙伴门户注册为技术合作伙伴。

« 定义构建集成 »