通过将 OpenTelemetry Collector 用作框架，释放其强大功能

原创于 2025-12-22 15:56:23 发布 · 330 阅读

5 ·

CC 4.0 BY-SA版权

本文为博主原创文章，未经博主允许不得转载。

文章标签：

#服务器 #大数据 #elasticsearch #搜索引擎 #elk #opentelmetry

Elastic 同时被 2 个专栏收录

2202 篇文章

订阅专栏

Observability

323 篇文章

订阅专栏

作者：来自 Elastic dmathieu

大多数人把 OpenTelemetry Collector 当作一个高级的 telemetry 路由器使用。但因为有时需要超越内置组件，在这个表面之下，它实际上是一个可插拔、可扩展的框架，旨在进行深度定制。

让我们看看如何将 Collector 用作一个框架。

为什么我要构建自定义 Collector？

没有两个 observability 堆栈是完全相同的。

你可能需要：

一个自制的 auth 层来处理传入的 telemetry
一个遵从性要求的数据清洗器
一个导出器，用于公司外没人听说过的系统
一个接收器，用于只存在于你工程传说中的协议

当内置组件无法满足需求时，Collector 提供了 API，让你可以干净、官方地编写缺失的部分。

🧩 Collector 里有什么？

使用 Collector 时，你将与以下一种（或多种）组件类型交互：

Receivers
它们接收数据并将其转换为内部数据类型，以供其他组件使用。

Processors
它们在传输中修改 telemetry，例如敏感数据脱敏、数据增强、采样等。

Exporters
它们获取处理后的数据，可能进行转换后发送到其他地方（另一个 Collector 或你的 observability 提供商）。

Extensions
它们处理所有非 telemetry 的功能：认证、健康检查等。

每种组件类型遵循相同模式：

一个 config struct（你的 YAML 设置）
一个 factory（Collector 如何创建你的组件）
一个组件实现（启动、关闭及处理逻辑）

让我们构建一个组件。

🔧 你的第一个 processor

让我们构建一个最小但可用的自定义 processor，为每个 span 添加一个属性。
这里是一个最小但可用的自定义 processor，为每个 span 添加一个属性。

已经有一个内置组件 attributesprocessor，可以为 span 添加属性。

模块设置

OpenTelemetry Collector 使用 Go 编写，每个组件都将插入其中。
因此每个组件都必须是一个 Go 模块。

本文假设你具备 Go 编程语言基础知识以及模块的使用方法。

你将需要一个 Go 模块：

mkdir otel-processor-example
cd otel-processor-example
go mod init

配置 struct

每个 Collector 组件都从一个 config.go 文件开始：

type Config struct {
    AttributeKey   string `mapstructure:"key"`
    AttributeValue string `mapstructure:"value"`
}

这将允许你像这样配置组件：

processors:
  addattribute:
    key: environment
    value: production

处理逻辑

这是组件内部实际执行的逻辑。
它可以启动一个 HTTP 服务器以接收请求（如果它是一个 receiver），发送外部 HTTP 请求（如果它是一个 exporter），或者更简单地，接收数据、进行转换并将其传递到下一个处理层。

func createTracesProcessor(
    ctx context.Context,
    set processor.CreateSettings,
    cfg component.Config,
) (processor.Traces, error) {
    conf := cfg.(*Config)

    return processorhelper.NewTracesProcessor(
        ctx,
        set,
        conf,
        func(ctx context.Context, td ptrace.Traces) (ptrace.Traces, error) {
            rs := td.ResourceSpans()

            for i := 0; i < rs.Len(); i++ {
                ils := rs.At(i).ScopeSpans()
                for j := 0; j < ils.Len(); j++ {
                    spans := ils.At(j).Spans()
                    for k := 0; k < spans.Len(); k++ {
                        span := spans.At(k)
                        span.Attributes().PutStr(conf.Key, conf.Value)
                    }
                }
            }

            return td, nil
        },
    )
}

在这种情况下，processor 会遍历 trace 数据，并为每个 span 添加一个属性。

Factory

Factory 将所有部分连接在一起：

func NewFactory() component.ProcessorFactory {
    return processor.NewFactory("addattribute", createDefaultConfig, processor.WithTraces(createTracesProcessor))
}

func createDefaultConfig() component.Config {
    return &Config{
        Key:   "env",
        Value: "default",
    }
}

这告诉 Collector，该组件名为 addattribute（因此你可以在配置中使用该名称），并且它可以处理 traces。

🏗️ 打包自定义 collector

现在你有了自定义组件，你会想使用它。
为此，你需要构建一个自定义 collector，并告诉它提供这个组件。

在一个新文件夹中（你的自定义 collector 与组件不同），创建一个 builder-config.yaml 文件：

dist:
  name: custom-collector
  description: "Collector with custom processor"
  output_path: ./dist

processors:
  addattribute:
    path: /path/to/your/component

然后，构建你自己的 Collector：

go install go.opentelemetry.io/collector/cmd/builder@latest
builder --config builder-config.yaml

你将在 dist 文件夹中得到一个自定义 Collector 二进制文件。

🚀 运行 collector

你可以像配置内置 processor 一样配置你的新 processor，通过配置 config.yaml：

receivers:
  otlp:

processors:
  addattribute:
    key: "environment"
    value: "staging"

exporters:
  logging:

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [addattribute]
      exporters: [logging]

启动 collector，发送一些 telemetry，你会看到你的自定义属性被添加到每个地方。