OpenTelemetry Collector 配置：组件都写了，为什么还是没生效

配置文件里该写的都写了，otelcol validate 也能过，但目标端就是没数据。多数时候不是语法问题——组件被定义了，却没有被 service 引用。

配置文件放哪、怎么加载

默认路径是 /etc//config.yaml，`` 通常是 otelcol 或 otelcol-contrib。

--config 可以传一个或多个文件，也支持 URI scheme：

• file:path/to/config.yaml
• env:MY_CONFIG_IN_AN_ENVVAR
• yaml:exporters::debug::verbosity: detailed（用 :: 分隔子路径）
• http://www.example.com / https://www.example.com

合并多份配置：

otelcol --config=file:/path/to/first --config=file:/path/to/second

合并后如果不构成完整配置会直接报错，因为必需组件不会默认补上。

校验单份配置：

otelcol validate --config=customconfig.yaml

四类管道组件，外加 extensions

访问遥测数据的管道组件有四类：接收器 receivers、处理器 processors、导出器 exporters、连接器 connectors。

另有 extensions，不直接处理遥测数据，提供 health_check、pprof、zpages 这类能力。

组件标识符格式是 type[/name]，例如 otlp 或 otlp/2。只要名字唯一，同一类型的组件可以定义多次。

官方示例（含 3 个扩展）：

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]

示例里用未指定地址 0.0.0.0 只是为了方便；当所有客户端都在本地时，绑 localhost 更合适。Collector 当前默认是 0.0.0.0，不远的将来默认值会改成 localhost。

配了组件 ≠ 启用

官方反复强调这一点：配置接收器、处理器、导出器、连接器、扩展功能，都不会让它启用。必须把组件加到 service 部分对应的管道里才生效。组件配置了但没在 service 里定义，就不会被启用。

service 部分含三个子段：extensions、pipelines、telemetry。

管道与 type[/name] 复用

管道类型有三种：traces（链路）、metrics（指标）、logs（日志）。一条管道由一组接收器、处理器、导出器组成。用 type[/name] 可以建额外管道，例如 traces/2。

• 同一个接收器可以出现在多条管道的 receivers 中，把相同数据送到多条管道。
• 多条管道也可以把数据发送到同一个导出器。
• 处理器顺序决定数据处理顺序。第一个处理器从管道配置的一个或多个接收器取数，最后一个处理器把数据发给一个或多个导出器。
• 同一个处理器名可以被多条管道的 processors 引用：配置相同，但每条管道获得独立实例，各有独立状态，从不跨管道共享（例如每条管道的 batch 都有自己的实例）。
• 同一个处理器名不能在单条管道的 processors 里重复引用。

service:
pipelines:
metrics:
receivers: [opencensus, prometheus]
exporters: [opencensus, prometheus]
traces:
receivers: [opencensus, jaeger]
processors: [memory_limiter]
exporters: [opencensus, zipkin]

复制语义：fanoutconsumer

一条管道可以有多个接收器：所有接收器的数据被推到第一个处理器，逐级传递，直到最后一个处理器把数据推给导出器。每个导出器都会收到每个数据元素的一份副本。最后一个处理器使用 fanoutconsumer 把数据发给多个导出器。

组件细节

接收器：从一或多个来源收集遥测数据，拉取型或推送型，支持一个或多个数据源。在 receivers 部分配置，很多有默认设置。示例：fluentforward endpoint 0.0.0.0:8006；hostmetrics 的 scrapers 有 cpu/disk/filesystem/load/memory/network/process/processes/paging；jaeger grpc 0.0.0.0:4317，以及 thrift_binary/thrift_compact/thrift_http；kafka protocol_version 2.0.0；opencensus；otlp grpc 0.0.0.0:4317（可配 tls 的 cert_file/key_file）、http 0.0.0.0:4318；prometheus 的 config.scrape_configs，job_name: otel-collector、scrape_interval: 5s、targets: [localhost:8888]；zipkin。

处理器：在发送前处理/转换数据，可过滤、丢弃、重命名、重算。处理器可选，但有些是推荐的。常见默认处理器示例：attributes（actions 支持 insert/delete/hash）；filter（error_mode: ignore，作用于 traces.span、spanevent、metrics.metric、datapoint、logs.log_record，表达式如 attributes["container.name"] == "app_container_1"、IsMatch(name, ".*grpc.*")、`severity_number

`mode` 必须设置。默认配置含：exporters `debug {}`；extensions `health_check {}`；processors `batch {}`、`memory_limiter`（`check_interval 5s`、`limit_percentage 80`、`spike_limit_percentage 25`）；receivers jaeger（`grpc ${env:MY_POD_IP}:14250`、`thrift_compact :6831`、`thrift_http :14268`）、otlp（`grpc :4317`、`http :4318`）、prometheus（`job_name opentelemetry-collector`、`scrape_interval 10s`、`targets ${env:MY_POD_IP}:8888`）、zipkin `:9411`；service 的 logs/metrics/traces 三条管道都用 processors `[memory_limiter, batch]` + exporters `[debug]`；`telemetry.metrics.address` 为 `${env:MY_POD_IP}:8888`。

可通过 values.yaml 的 `config` 部分改配置。改流水线时必须显式列出流水线里的所有组件，包括默认组件。

可用 `null` 删除默认配置（如 `receivers.jaeger: null`），或在 values.yaml 禁用端口（`ports.jaeger-grpc.enabled: false` 等）。

presets 应作为起点：

- logsCollection：需 Filelog 接收器，建议 daemonset；只收本节点日志，同节点多 Collector 会重复数据。
- kubernetesAttributes：加 RBAC，并把 k8sattributesprocessor 加到每个流水线。
- kubeletMetrics：需 Kubeletstats 接收器，建议 daemonset，只收本节点。
- clusterMetrics：需 k8sclusterreceiver，建议 deployment 或单副本 statefulset，多副本会重复数据。
- kubernetesEvents：需 k8sobjectsreceiver，建议 deployment。
- hostMetrics：需 hostmetricsreceiver，每 10s 抓 cpu/load/memory/disk/filesystem/network。

**日志爆炸**：默认日志流水线用 debugexporter，与 logsCollection 的 filelogreceiver 配对时可能把日志导回 Collector 形成循环。默认排除 Collector 自身日志；若要 `includeCollectorLogs: true`，需把 debug 导出器换成不写标准输出的（如 `otlphttp` 指向 `https://example.com:55681`）。

## 参考

- 配置文档：https://opentelemetry.io/zh/docs/collector/configuration/
- 架构文档：https://opentelemetry.io/zh/docs/collector/architecture/
- K8s Helm Chart：https://opentelemetry.io/zh/docs/platforms/kubernetes/helm/collector/
- Collector 仓库：https://github.com/open-telemetry/opentelemetry-collector
- Helm charts 仓库：https://github.com/open-telemetry/opentelemetry-helm-charts