« 创建指标集 创建 Metricbeat 模块 »
Elastic 文档 ›Beats 开发者指南 [master] ›扩展 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。如果在请求完成之前超时到期，则必须结束请求并返回错误以确保下一个请求能够按时启动。默认情况下，超时设置为 Period，因此在发出新请求之前会结束一个请求。

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

数据转换编辑

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

fields.yml编辑

您可以在 Beats 存储库中为每个 Metricbeat 模块找到最多 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_major_version} 编写的，基于我们的小型 Python 测试框架。我们使用 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 模块 »