有更新的版本可用。如需获取最新信息，请参阅当前版本文档。
« 创建指标集 创建 Metricbeat 模块 »
Elastic 文档 ›Beats 开发者指南 [8.14] ›扩展 Metricbeat

指标集详细信息

编辑

指标集详细信息编辑

本主题提供有关创建指标集的更多详细信息。

添加特殊配置选项编辑

每个指标集都可以定义自己的配置变量。要使用这些变量，您必须扩展 New 方法。例如，假设您要向指标集添加 password 配置选项。您将按以下方式扩展 beat.yml

metricbeat.modules:
- module: {module}
  metricsets: ["{metricset}"]
  password: "test1234"

要读入新的 password 配置选项，您需要修改 New 方法。首先，您需要定义一个包含要读取的值类型的配置结构体。您可以根据需要设置默认值。然后，您将配置传递给 UnpackConfig 方法以加载配置。

您的实现应该如下所示

type MetricSet struct {
	mb.BaseMetricSet
	password string
}

func New(base mb.BaseMetricSet) (mb.MetricSet, error) {

	// Unpack additional configuration options.
	config := struct {
		Password string `config:"password"`
	}{
		Password: "",
	}
	err := base.Module().UnpackConfig(&config)
	if err != nil {
		return nil, err
	}

	return &MetricSet{
		BaseMetricSet: base,
		password:      config.Password,
	}, nil
}

服务连接超时编辑

每次调用 Fetch 方法时，它都会向服务发出请求，因此正确处理连接非常重要。我们建议您在 New 方法中设置连接，并将其持久化到 MetricSet 对象中。这允许重复使用连接。

非常重要的一点是，连接必须遵守超时变量：base.Module().Config().Timeout。如果在请求完成之前超时，则必须结束请求并返回错误，以确保可以按时启动下一个请求。默认情况下，Timeout 设置为 Period，因此在一个请求开始之前，前一个请求会被结束。

如果必须结束请求或请求出错，请确保返回有用的错误消息。此错误消息也会发送到 Elasticsearch，从而不仅可以从服务中获取指标，还可以报告指标集的潜在问题或错误。

数据转换编辑

如果必须在 Fetch 方法中进行的数据转换非常广泛，我们建议您在与指标集相同的包中创建第二个名为 data.go 的文件。data.go 文件应包含一个名为 eventMapping(...) 的函数。不需要单独的文件，但目前这是最佳实践，因为它将指标集和 Fetch 方法的功能与数据映射隔离。

fields.yml编辑

您可以在每个 metricbeat 模块的 beats 存储库中找到多达 3 种不同类型的文件，名为 fields.yml

  • metricbeat/fields.yml：包含用于创建 Elasticsearch 模板、Kibana 索引模式配置和指标集的导出字段文档的定义。为了确保 Elasticsearch 模板正确无误，请务必使用所有更改更新此文件。通常，您不应该手动修改此文件，因为它是由构建环境中的一些命令生成的。

  • metricbeat/module/{module}/_meta/fields.yml：包含模块中所有指标集的通用顶级结构。通常，您只需要修改此文件中的描述。以下是 MySQL 模块的 fields.yml 文件示例。

    - key: mysql
  title: "MySQL"
  description: >
    MySQL server status metrics collected from MySQL.
  short_config: false
  release: ga
  fields:
    - name: mysql
      type: group
      description: >
        `mysql` contains the metrics that were obtained from MySQL
        query.
      fields:

  • metricbeat/module/{module}/{metricset}/_meta/fields.yml：包含由指标集检索的所有字段定义。作为字段类型，每个字段都必须具有elasticsearch 支持的核心数据类型。以下是一个非常基本的示例，它显示了 MySQL status 指标集中的一个组

    - name: status
  type: group
  description: >
    `status` contains the metrics that were obtained by the status SQL query.
  fields:
    - name: aborted
      type: group
      description: Aborted status fields.
      fields:
        - name: clients
          type: integer
          description: >
            The number of connections that were aborted because the client died without closing the connection properly.

        - name: connects
          type: integer
          description: >
            The number of failed attempts to connect to the MySQL server.

测试编辑

为指标集添加测试也很重要。测试 Beat 需要三种不同类型的测试

  • 单元测试
  • 集成测试
  • 系统测试

我们建议您在创建指标集时同时使用这三种测试。单元测试用 Go 编写，没有依赖项。集成测试也用 Go 编写，但要求模块从中收集指标的服务也在运行。Metricbeat 的系统测试在大多数情况下也要求服务正在运行，并且基于我们的小型 Python 测试框架用 Python {python_major_version} 编写。我们使用 venv 来处理 Python 依赖项。您可以简单地运行命令 make python-env，然后运行 . build/python-env/bin/activate 。

您应该结合使用三种测试类型来测试指标集，因为每种方法都有优缺点。要开始编写自己的测试，最好先看看现有的测试。您可以在现有模块和指标集下的 _test.go 文件中找到单元测试和集成测试。集成测试通常采用 TestFetch 和 TestData 的形式。系统测试位于 tests/systems 下。

添加测试环境编辑

集成测试和系统测试需要一个正在运行服务的环境。您可以使用 Docker 和 docker-compose 文件创建此环境。如果您添加的模块需要服务，则必须将服务添加到虚拟环境中。为此，您需要

  • 使用您的环境更新 docker-compose.yml 文件
  • 更新 docker-entrypoint.sh 脚本

docker-compose.yml 文件位于 Metricbeat 的根目录下。大多数服务都有现有的 Docker 模块，可以像 Redis 一样简单地添加

redis:
  image: redis:3.2.3

为了让 Beat 能够访问您的服务，请确保在 docker-compose 文件中定义了环境变量，并添加了指向容器的链接

beat:
  links:
    - redis
  environment:
    - REDIS_HOST=redis
    - REDIS_PORT=6379

为了确保服务在测试开始之前就已经运行，请修改 docker-entrypoint.sh 脚本以添加一项检查，验证您的服务是否正在运行。例如，对 Redis 的检查如下所示

waitFor ${REDIS_HOST} ${REDIS_PORT} Redis

环境期望您的服务在收到来自给定地址和端口的响应后立即可用。

添加标准指标集集成测试编辑

通常，每个指标集都包含两个集成测试：TestFetch 和 TestData。这两个测试都会启动您的指标集的新实例并获取一个事件。为了启动指标集，您需要创建一个配置对象

func getConfig() map[string]interface{} {
    return map[string]interface{}{
    "module":           "{module}",
    "metricsets":       []string{"{metricset}"},
    "hosts":      []string{GetEnvHost() + ":" + GetEnvPort()}, 
  }
}

func GetEnvHost() string { 
    host := os.Getenv("{module}_HOST")
    if len(host) == 0 {
    host = "127.0.0.1"
  }
  return host
}

func GetEnvPort() string { 
    port := os.Getenv("{module}_PORT")

    if len(port) == 0 {
      port = "1234"
    }
  return port
}

在此处添加您的指标集需要的任何其他配置选项。

指标集使用的端点需要可配置，以便进行手动和自动测试。环境变量应在 _meta/env 下的模块中定义，并包含在 docker-compose.yml 文件中。

TestFetch 集成测试将从您的指标集中返回一个事件，您可以使用该事件来测试数据的有效性。TestData 将（重新）生成 _meta/data.json 文件，该文件记录指标集报告的数据。

import (
	"os"
	"testing"

	"github.com/stretchr/testify/assert"

	"github.com/elastic/beats/libbeat/tests/compose"
	mbtest "github.com/elastic/beats/metricbeat/mb/testing"
)

func TestFetch(t *testing.T) {
	compose.EnsureUp(t, "{module}") 

	f := mbtest.NewReportingMetricSetV2Error(t, getConfig())

	events, errs := mbtest.ReportingFetchV2Error(f)
	if len(errs) > 0 {
		t.Fatalf("Expected 0 errord, had %d. %v\n", len(errs), errs)
	}

	assert.NotEmpty(t, events) 

}

func TestData(t *testing.T) {

	f := mbtest.NewReportingMetricSetV2Error(t, getConfig())

	err := mbtest.WriteEventsReporterV2Error(f, t, "") 
	if !assert.NoError(t, err) {
		t.FailNow()
	}
}

使用此命令启动与您的指标集关联的 docker 服务。

添加任何进一步的有效性检查，以验证指标集是否正常工作。

WriteEventsReporterV2Error 将从指标集中获取第一个有效事件，并将其写入 _meta/data.json
运行测试编辑

要运行所有测试，请运行 make testsuite。要仅运行单元测试，请运行 mage unitTest，要运行集成测试，请运行 mage integTest。请注意，集成测试和系统测试需要运行 Docker 环境。

要运行 TestData 并生成 data.json 文件，请在测试所在的目录中运行 go test -tags=integration -data -run TestData。

要为单个模块运行集成测试，请将 MODULE 环境变量设置为模块目录的名称。例如，您可以运行以下命令来为 apache 模块运行集成测试

MODULE=apache mage integTest

文档编辑

必须记录每个模块。文档基于 asciidoc，模块的文档位于文件 module/{module}/_meta/docs.asciidoc 中，指标集的文档位于 module/{module}/{metricset}/_meta/docs.asciidoc 中。包含配置文件和示例输出的基本文档会自动生成。使用这些文件来记录特定的配置选项或使用示例。

« 创建指标集 创建 Metricbeat 模块 »