了解如何根据需要配置 Collector
你可以根据可观测性需求配置 OpenTelemetry Collector。了解 Collector 配置的工作方式之前,请先熟悉以下内容:
- 数据收集概念,了解适用于 OpenTelemetry Collector 的代码仓库。
- 面向最终用户的安全指南
- 面向组件开发者的安全指南
配置位置
默认情况下,Collector 配置位于 /etc/<otel-directory>/config.yaml。<otel-directory> 可以是 otelcol、otelcol-contrib 或其他值,具体取决于 Collector 版本或你使用的发行版。
可以通过 --config 选项提供一个或多个配置。例如:
otelcol --config=customconfig.yaml
--config 标志接受文件路径,也接受 "<scheme>:<opaque_data>" 形式的配置 URI。目前,OpenTelemetry Collector 支持以下 scheme 配置提供程序:
- file:从文件读取配置,例如
file:path/to/config.yaml。 - env:从环境变量读取配置,例如
env:MY_CONFIG_IN_AN_ENVVAR。 - yaml:从 YAML 字符串读取配置,使用
::分隔子路径,例如yaml:exporters::debug::verbosity: detailed。 - http:从 HTTP URI 读取配置,例如
http://www.example.com。 - https:从 HTTPS URI 读取配置,例如
https://www.example.com。
也可以使用不同路径下的多个文件提供多个配置。每个文件可以包含完整配置或部分配置,文件之间可以相互引用组件。如果文件合并后无法构成完整配置,用户会收到错误,因为必需组件不会默认添加。可以像下面这样在命令行中传入多个文件路径:
otelcol --config=file:/path/to/first/file --config=file:/path/to/second/file
也可以使用环境变量、HTTP URI 或 YAML 路径提供配置。例如:
otelcol --config=env:MY_CONFIG_IN_AN_ENVVAR --config=https://server/config.yaml
otelcol --config="yaml:exporters::debug::verbosity: normal"
使用 validate 命令验证配置文件。例如:
otelcol validate --config=customconfig.yaml
配置结构
Collector 配置文件的结构包含四类访问遥测数据的流水线组件:
配置每个流水线组件后,必须通过配置文件 service 部分中的流水线启用它。
除流水线组件外,还可以配置 扩展(extensions),为 Collector 添加诊断工具等功能。扩展不要求直接访问遥测数据,也通过 service 部分启用。
下面的 Collector 配置示例包含一个接收器、一个处理器、一个导出器和三个扩展。
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
exporters:
otlp_grpc:
endpoint: otelcol:4317
sending_queue:
batch:
extensions:
health_check:
endpoint: 0.0.0.0:13133
pprof:
endpoint: 0.0.0.0:1777
zpages:
endpoint: 0.0.0.0:55679
service:
extensions: [health_check, pprof, zpages]
pipelines:
traces:
receivers: [otlp]
exporters: [otlp_grpc]
metrics:
receivers: [otlp]
exporters: [otlp_grpc]
logs:
receivers: [otlp]
exporters: [otlp_grpc]
注意,接收器、处理器、导出器和流水线通过 type[/name] 格式的组件标识符定义,例如 otlp 或 otlp/2。只要标识符唯一,就可以多次定义同一类型的组件。例如:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
otlp/2:
protocols:
grpc:
endpoint: 0.0.0.0:55690
exporters:
otlp_grpc:
endpoint: otelcol:4317
sending_queue:
batch:
otlp_grpc/2:
endpoint: otelcol2:4317
sending_queue:
batch:
extensions:
health_check:
endpoint: 0.0.0.0:13133
pprof:
endpoint: 0.0.0.0:1777
zpages:
endpoint: 0.0.0.0:55679
service:
extensions: [health_check, pprof, zpages]
pipelines:
traces:
receivers: [otlp]
exporters: [otlp_grpc]
traces/2:
receivers: [otlp/2]
exporters: [otlp_grpc/2]
metrics:
receivers: [otlp]
exporters: [otlp_grpc]
logs:
receivers: [otlp]
exporters: [otlp_grpc]
配置还可以包含其他文件,使 Collector 将它们合并为内存中的单一 YAML 配置表示:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
exporters: ${file:exporters.yaml}
service:
extensions: []
pipelines:
traces:
receivers: [otlp]
processors: []
exporters: [otlp_grpc]
其中,exporters.yaml 文件内容为:
otlp_grpc:
endpoint: otelcol.observability.svc.cluster.local:443
最终在内存中得到的结果为:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
exporters:
otlp_grpc:
endpoint: otelcol.observability.svc.cluster.local:443
service:
extensions: []
pipelines:
traces:
receivers: [otlp]
processors: []
exporters: [otlp_grpc]
接收器 
接收器从一个或多个来源收集遥测数据。它们可以采用拉取方式,也可以采用推送方式,并可能支持一种或多种 数据源。
接收器在 receivers 部分配置。许多接收器提供默认设置,因此只指定接收器名称便足以完成配置。如果需要配置接收器或修改默认配置,可以在这一部分进行。你指定的任何设置都会覆盖已有默认值。
Collector 需要至少一个接收器。下面的示例在同一配置文件中展示了多种接收器:
receivers:
# Data sources: logs
fluentforward:
endpoint: 0.0.0.0:8006
# Data sources: metrics
host_metrics:
scrapers:
cpu:
disk:
filesystem:
load:
memory:
network:
process:
processes:
paging:
# Data sources: traces
jaeger:
protocols:
grpc:
endpoint: 0.0.0.0:4317
thrift_binary:
thrift_compact:
thrift_http:
# Data sources: traces, metrics, logs
kafka:
protocol_version: 2.0.0
# Data sources: traces, metrics
opencensus:
# Data sources: traces, metrics, logs
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
tls:
cert_file: cert.pem
key_file: cert-key.pem
http:
endpoint: 0.0.0.0:4318
# Data sources: metrics
prometheus:
config:
scrape_configs:
- job_name: otel-collector
scrape_interval: 5s
static_configs:
- targets: [localhost:8888]
# Data sources: traces
zipkin:
处理器 
处理器接收接收器收集的数据,在发送给导出器之前对其进行修改或转换。数据处理遵循各处理器定义的规则或设置,可能包括过滤、丢弃、重命名、重新计算遥测数据等操作。流水线中处理器的顺序决定 Collector 对信号执行处理操作的顺序。
处理器是可选的,不过官方 建议使用某些处理器。
可以通过 Collector 配置文件的 processors 部分配置处理器。你指定的任何设置都会覆盖已有默认值。
下面的示例在同一配置文件中展示了几个默认处理器。合并 opentelemetry-collector-contrib 与 opentelemetry-collector 中的处理器列表,就能得到完整列表。
processors:
# Data sources: traces
attributes:
actions:
- key: environment
value: production
action: insert
- key: db.statement
action: delete
- key: email
action: hash
# Data sources: traces, metrics, logs
filter:
error_mode: ignore
traces:
span:
- 'attributes["container.name"] == "app_container_1"'
- 'resource.attributes["host.name"] == "localhost"'
- 'name == "app_3"'
spanevent:
- 'attributes["grpc"] == true'
- 'IsMatch(name, ".*grpc.*")'
metrics:
metric:
- 'name == "my.metric" and resource.attributes["my_label"] == "abc123"'
- 'type == METRIC_DATA_TYPE_HISTOGRAM'
datapoint:
- 'metric.type == METRIC_DATA_TYPE_SUMMARY'
- 'resource.attributes["service.name"] == "my_service_name"'
logs:
log_record:
- 'IsMatch(body, ".*password.*")'
- 'severity_number < SEVERITY_NUMBER_WARN'
# Data sources: traces, metrics, logs
memory_limiter:
check_interval: 5s
limit_mib: 4000
spike_limit_mib: 500
# Data sources: traces
resource:
attributes:
- key: cloud.zone
value: zone-1
action: upsert
- key: k8s.cluster.name
from_attribute: k8s-cluster
action: insert
- key: redundant-attribute
action: delete
# Data sources: traces
probabilistic_sampler:
hash_seed: 22
sampling_percentage: 15
# Data sources: traces
span:
name:
to_attributes:
rules:
- ^\/api\/v1\/document\/(?P<documentId>.*)\/update$
from_attributes: [db.svc, operation]
separator: '::'
导出器 
导出器将数据发送到一个或多个后端或目标。它们可以采用拉取方式,也可以采用推送方式,并可能支持一种或多种 数据源。
exporters 部分中的每个键定义一个导出器实例。键使用 type/name 格式,其中 type 指定导出器类型,例如 otlp、kafka、prometheus;可选的 name 可以附加在后面,为同一类型的多个实例提供唯一名称。
大多数导出器至少需要配置目标地址,以及身份验证令牌或 TLS 证书等安全设置。你指定的任何设置都会覆盖已有默认值。
Collector 需要至少一个导出器。下面的示例在同一配置文件中展示了多种导出器:
exporters:
# Data sources: traces, metrics, logs
file:
path: ./filename.json
# Data sources: traces
otlp_grpc/jaeger:
endpoint: jaeger-server:4317
tls:
cert_file: cert.pem
key_file: cert-key.pem
# Data sources: traces, metrics, logs
kafka:
protocol_version: 2.0.0
# Data sources: traces, metrics, logs
# NOTE: Prior to v0.86.0 use `logging` instead of `debug`
debug:
verbosity: detailed
# Data sources: traces, metrics
opencensus:
endpoint: otelcol2:55678
# Data sources: traces, metrics, logs
otlp_grpc:
endpoint: otelcol2:4317
tls:
cert_file: cert.pem
key_file: cert-key.pem
# Data sources: traces, metrics
otlp_http:
endpoint: https://otlp.example.com:4318
# Data sources: metrics
prometheus:
endpoint: 0.0.0.0:8889
namespace: default
# Data sources: metrics
prometheus_remote_write:
endpoint: http://prometheus.example.com:9411/api/prom/push
# When using the official Prometheus (running via Docker)
# endpoint: 'http://prometheus:9090/api/v1/write', add:
# tls:
# insecure: true
# Data sources: traces
zipkin:
endpoint: http://zipkin.example.com:9411/api/v2/spans
注意,有些导出器需要 X.509 证书才能建立安全连接,详见 配置证书。
连接器 
连接器连接两条流水线,同时充当导出器和接收器。连接器在一条流水线末端以导出器身份消费数据,在另一条流水线开端以接收器身份发出数据。消费和发出的数据可以是同一种类型,也可以是不同类型。连接器可用于汇总消费的数据、复制数据或进行路由。
可以通过 Collector 配置文件的 connectors 部分配置一个或多个连接器。默认不配置连接器。每一种连接器都为一种或多种数据类型配对设计,只能用于连接相应的流水线。
下面的示例展示 count 连接器及其在 pipelines 部分的配置方式。注意,它充当 traces 的导出器和 metrics 的接收器,将两条流水线连接起来:
receivers:
foo:
exporters:
bar:
connectors:
count:
spanevents:
my.prod.event.count:
description: The number of span events from my prod environment.
conditions:
- 'attributes["env"] == "prod"'
- 'name == "prodevent"'
service:
pipelines:
traces:
receivers: [foo]
exporters: [count]
metrics:
receivers: [count]
exporters: [bar]
扩展 
扩展是可选组件,用于扩展 Collector 的能力,完成不直接涉及遥测数据处理的任务。例如,可以添加用于 Collector 健康监控、服务发现或数据转发的扩展。
可以通过 Collector 配置文件的 extensions 部分配置扩展。大多数扩展提供默认设置,因此只指定扩展名称即可配置。你指定的任何设置都会覆盖已有默认值。
默认不配置扩展。下面的示例在同一文件中配置了多个扩展:
extensions:
health_check:
endpoint: 0.0.0.0:13133
pprof:
endpoint: 0.0.0.0:1777
zpages:
endpoint: 0.0.0.0:55679
Service 部分
service 部分依据 receivers、processors、exporters 和 extensions 部分中的配置,确定 Collector 中启用哪些组件。组件即使已经配置,只要没有在 service 部分定义,就不会启用。
service 部分包含三个子部分:
- Extensions(扩展)
- Pipelines(流水线)
- Telemetry(遥测)
扩展
extensions 子部分包含需要启用的扩展列表。例如:
service:
extensions: [health_check, pprof, zpages]
流水线
pipelines 子部分用于配置流水线,可以是以下类型:
traces:收集和处理追踪数据。metrics:收集和处理指标数据。logs:收集和处理日志数据。
一条流水线由一组接收器、处理器和导出器组成。在将接收器、处理器或导出器加入流水线之前,务必在相应部分定义其配置。
可以在多条流水线中使用同一个接收器、处理器或导出器。当多条流水线引用同一个处理器时,每条流水线都会获得该处理器的独立实例。
下面是流水线配置示例。注意,处理器的顺序决定数据处理的顺序:
service:
pipelines:
metrics:
receivers: [opencensus, prometheus]
exporters: [opencensus, prometheus]
traces:
receivers: [opencensus, jaeger]
processors: [memory_limiter]
exporters: [opencensus, zipkin]
与组件一样,使用 type[/name] 语法可以为同一类型创建额外流水线。下面的示例扩展了前面的配置:
service:
pipelines:
# ...
traces:
# ...
traces/2:
receivers: [opencensus]
exporters: [zipkin]
遥测
telemetry 配置部分用于设置 Collector 自身的可观测性。它包含 logs 和 metrics 两个子部分。了解如何配置这些信号,请参阅 激活 Collector 内部遥测。
其他信息
环境变量
Collector 配置支持使用和展开环境变量。例如,要使用 DB_KEY 和 OPERATION 环境变量中存储的值,可以编写以下配置:
processors:
attributes/example:
actions:
- key: ${env:DB_KEY}
action: ${env:OPERATION}
可以使用 Bash 语法为环境变量提供默认值:${env:DB_KEY:-some-default-var}。
processors:
attributes/example:
actions:
- key: ${env:DB_KEY:-mydefault}
action: ${env:OPERATION:-}
使用 $$ 表示字面量 $。例如,表示 $DataVisualization 时应写成以下形式:
exporters:
prometheus:
endpoint: prometheus:8889
namespace: $$DataVisualization
代理支持
使用 net/http 包的导出器遵循以下代理环境变量:
HTTP_PROXY:HTTP 代理地址。HTTPS_PROXY:HTTPS 代理地址。NO_PROXY:不得使用代理的地址。
如果在 Collector 启动时设置这些环境变量,无论协议为何,导出器都会按照它们的定义通过代理发送流量或绕过代理。
身份验证
大多数开放 HTTP 或 gRPC 端口的接收器可以使用 Collector 的身份验证机制进行保护。同样,大多数使用 HTTP 或 gRPC 客户端的导出器可以为发出的请求添加身份验证。
Collector 的身份验证机制基于扩展机制,因此可将自定义身份验证器插入 Collector 发行版。每个身份验证扩展有两种可能的用法:
- 为导出器充当客户端身份验证器,向发出的请求添加身份验证数据。
- 为接收器充当服务器身份验证器,验证传入连接。
已知身份验证器列表请参阅 注册表。如果希望开发自定义身份验证器,请参阅 构建身份验证器扩展。
在 Collector 中为接收器添加服务器身份验证器时,请执行以下步骤:
- 在
.extensions下添加身份验证器扩展及其配置。 - 在
.services.extensions中添加对身份验证器的引用,以便 Collector 加载它。 - 在
.receivers.<your-receiver>.<http-or-grpc-config>.auth下添加对身份验证器的引用。
下面的示例在接收器端使用 OIDC 身份验证器,适合由作为代理的 OpenTelemetry Collector 向远程 Collector 发送数据的场景。
extensions:
oidc:
issuer_url: http://localhost:8080/auth/realms/opentelemetry
audience: collector
receivers:
otlp/auth:
protocols:
grpc:
endpoint: 0.0.0.0:4317
auth:
authenticator: oidc
processors:
exporters:
# NOTE: Prior to v0.86.0 use `logging` instead of `debug`.
debug:
service:
extensions:
- oidc
pipelines:
traces:
receivers:
- otlp/auth
processors: []
exporters:
- debug
在代理端,下面的示例使 OTLP 导出器获取 OIDC 令牌,并将其添加到发往远程 Collector 的每个 RPC 中:
extensions:
oauth2client:
client_id: agent
client_secret: some-secret
token_url: http://localhost:8080/auth/realms/opentelemetry/protocol/openid-connect/token
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
processors:
exporters:
otlp_grpc/auth:
endpoint: remote-collector:4317
auth:
authenticator: oauth2client
service:
extensions:
- oauth2client
pipelines:
traces:
receivers:
- otlp
processors: []
exporters:
- otlp_grpc/auth
配置证书
在生产环境中,使用 TLS 证书保护通信,或使用 mTLS 进行双向身份验证。下面的步骤展示如何生成示例中的自签名证书。用于生产时,可以采用你现有的证书供应流程获取证书。
安装 cfssl,然后创建以下 csr.json 文件:
{
"hosts": ["localhost", "127.0.0.1"],
"key": {
"algo": "rsa",
"size": 2048
},
"names": [
{
"O": "OpenTelemetry Example"
}
]
}
然后运行以下命令:
cfssl genkey -initca csr.json | cfssljson -bare ca
cfssl gencert -ca ca.pem -ca-key ca-key.pem csr.json | cfssljson -bare cert
这会创建两个证书:
ca.pem中的“OpenTelemetry Example”证书颁发机构(CA),以及ca-key.pem中的关联密钥。cert.pem中的客户端证书,由 OpenTelemetry Example CA 签名,其关联密钥位于cert-key.pem。
在 Collector 中使用证书
获得证书后,配置 Collector 使用它们。
接收器的 TLS 配置(服务器端)
在接收器上配置 TLS,以加密传入连接。使用 cert_file 和 key_file 指定服务器证书:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
tls:
cert_file: /path/to/cert.pem
key_file: /path/to/cert-key.pem
http:
endpoint: 0.0.0.0:4318
tls:
cert_file: /path/to/cert.pem
key_file: /path/to/cert-key.pem
导出器的 TLS 配置(客户端)
在导出器上配置 TLS,以加密发出的连接。使用 ca_file 验证服务器证书:
exporters:
otlp_grpc:
endpoint: otelcol2:4317
tls:
ca_file: /path/to/ca.pem
如果还需要向服务器提供客户端证书:
exporters:
otlp_grpc:
endpoint: otelcol2:4317
tls:
ca_file: /path/to/ca.pem
cert_file: /path/to/cert.pem
key_file: /path/to/cert-key.pem
mTLS 配置(双向 TLS)
对于 mTLS,接收器和导出器都会验证对方的证书。在接收器上添加 client_ca_file 来验证客户端证书:
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
tls:
cert_file: /path/to/server-cert.pem
key_file: /path/to/server-key.pem
client_ca_file: /path/to/ca.pem
在导出器上,同时提供验证服务器所需的 CA 证书和客户端证书:
exporters:
otlp_grpc:
endpoint: remote-collector:4317
tls:
ca_file: /path/to/ca.pem
cert_file: /path/to/client-cert.pem
key_file: /path/to/client-key.pem
常见 TLS 设置
TLS 配置支持以下设置:
| 设置 | 说明 |
|---|---|
ca_file |
用于验证对端证书的 CA 证书路径 |
cert_file |
TLS 证书路径 |
key_file |
TLS 私钥路径 |
client_ca_file |
用于验证客户端证书的 CA 证书路径 |
insecure |
禁用 TLS 验证(不建议用于生产) |
insecure_skip_verify |
跳过服务器证书验证(不建议) |
min_version |
最低 TLS 版本,例如 1.2 或 1.3 |
max_version |
最高 TLS 版本 |
reload_interval |
重新加载证书的时间间隔 |
覆盖设置
可以使用 --set 选项覆盖 Collector 设置。以这种方式定义的设置会在所有 --config 来源解析并合并之后,再合并到最终配置中。
以下示例展示如何覆盖嵌套部分中的设置:
简单属性
--set 选项始终接受一个键值对,用法为 --set key=value。对应的 YAML 为:
key: value
复杂嵌套键
在键值对名称中使用双冒号 :: 作为键分隔符,可以引用嵌套映射值。例如,--set outer::inner=value 转换为:
outer:
inner: value
多个值
要设置多个值,请指定多个 --set 标志。因此,--set a=b --set c=d 会转换为:
a: b
c: d
数组值
用 [] 将值括起来,可以表示数组。例如,--set "key=[a, b, c]" 转换为:
key:
- a
- b
- c
如果需要表示更复杂的数据结构,强烈建议使用 YAML。
--set 选项有以下限制:
- 不支持设置包含点号
.的键。 - 不支持设置包含等号
=的键。 - 属性值部分中的配置键分隔符为
::。例如,--set "name={a::b: c}"等价于--set name::a::b=c。
嵌入其他配置提供程序
一个配置提供程序可以引用其他配置提供程序,如下所示:
receivers:
otlp:
protocols:
grpc:
exporters: ${file:otlp-exporter.yaml}
service:
extensions: []
pipelines:
traces:
receivers: [otlp]
processors: []
exporters: [otlp_grpc]
检查发行版中可用的组件
使用 build-info 子命令。下面是示例:
otelcol components
示例输出:
buildinfo:
command: otelcol
description: OpenTelemetry Collector
version: 0.143.0
receivers:
- otlp
processors:
- memory_limiter
exporters:
- otlp_grpc
- otlp_http
- debug
extensions:
- zpages
检查最终配置
在默认模式 --mode=redacted 下使用 print-config,并启用 --feature-gates=otelcol.printInitialConfig:
otelcol print-config --config=file:examples/local/otel-config.yaml
注意,默认只会打印有效配置,并会对敏感信息进行脱敏。要打印可能无效的配置,请使用 --validate=false。
查看敏感字段
使用 print-config,设置 --mode=unredacted 并启用 --feature-gates=otelcol.printInitialConfig:
otelcol print-config --mode=unredacted --config=file:examples/local/otel-config.yaml
以 JSON 格式打印最终配置
使用 print-config,设置 --format=json 并启用 --feature-gates=otelcol.printInitialConfig。注意,JSON 格式被视为不稳定。
otelcol print-config --format=json --config=file:examples/local/otel-config.yaml











暂无评论内容