« 创建指标集 创建 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。如果在请求完成之前超时到期，则必须结束请求并返回错误，以确保可以及时启动下一个请求。默认情况下，超时设置为周期，因此在一个新请求发出之前，一个请求将结束。

如果必须结束请求或发生错误，请确保返回有用的错误消息。此错误消息也会发送到 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 {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 模块 »