otel-collector

OpenTelemetry Collector

本技能涵盖各个 OpenTelemetry Collector 组件的配置范围，适用于 opentelemetry-collector 和 opentelemetry-collector-contrib。

本技能不涵盖 OTTL 表达式（参见 otel-ottl）、声明式 SDK 配置（otel-declarative-config）、部署 eBPF 分析器或其他 profiles 生成器（otel-profiles），也不涵盖端到端管道设计选择。如果问题涉及转换语言、SDK 设置或管道组合，请使用相应技能。

工作流程

1. 识别组件。 在用户的配置或问题中查找 type（log_dedup、interval、otlp 等）。请注意，自 v0.146.0 起，许多组件已重命名为 snake_case，同时保留了已弃用的别名——参见近期重命名。
2. 回答前先加载组件页面。 如果组件列在组件索引中，务必先阅读 components/<type>/README.md——顶层索引仅用于指引，不能作为回答的充分依据。按照其详情索引找到最相关的文件：有关版本化配置键、默认值或验证的信息，请阅读 configuration.md；有关稳定性、可用性、故障行为或迁移注意事项的信息，请阅读 quirks.md；其他详情文件则根据问题需要阅读。不要根据摘要行或记忆推断具体配置或状态。
3. 如果组件未编入索引，请明确说明，并转而查阅 opentelemetry-collector-contrib 中 processor/<name>/、receiver/<name>/、exporter/<name>/、connector/<name>/ 或 extension/<name>/ 下的上游 README。不要凭记忆编造配置键——Collector 组件变化很快。
4. 应用 Collector 通用约定。 Collector 通用约定中的命名实例（type/name）、稳定性级别和管道放置规则适用于所有组件。
5. 验证。 按照组件页面的验证步骤操作——使用 telemetrygen（参见 otel-telemetrygen 技能）以及 debug 或 file 导出器，确认组件的行为符合文档说明。此处经常涉及 Alpha 和 Development 稳定性级别的组件，其行为会随版本变化。有关如何端到端运行验证步骤，请参见验证测试框架。

组件索引

每个组件都是 components/<type>/ 下的一个目录。File 列指向精简的 README.md（其中包含元数据、描述、主要使用场景和详情索引）；完整配置参考、验证步骤、高级使用场景和注意事项位于该 README 链接的按需详情文件中。

此处的覆盖范围经过有意筛选。如果组件未编入索引，请针对用户使用的 Collector 版本查阅上游组件 README。

验证日期：2026-10-25：此处及组件 README 标题中的稳定性单元格与核心仓库及 contrib 仓库 v0.163.0 中的 metadata.yaml 相符；重命名版本和“自……起”版本与指定标签及其前一个标签中的 metadata.yaml 相符。离线时，请引用该版本和日期，而非当前稳定性。

类型	文件	类型	信号	稳定性	摘要
log_dedup	components/log_dedup/README.md	处理器	日志	Alpha	在时间窗口内对相同日志记录去重；输出一条带计数的聚合日志。v0.151.0 中从 logdedup 重命名而来；保留别名。
interval	components/interval/README.md	处理器	指标	Alpha	缓冲指标，并按间隔为每个序列输出一个数据点：对于累积单调序列、仪表和摘要，输出最新值；对于增量序列，输出求和值。非单调求和指标原样传递。
tail_sampling	components/tail_sampling/README.md	处理器	跟踪	Beta	缓冲完整跟踪，并在等待窗口结束后通过策略做出一次保留/丢弃决定。通过 num_shards 支持进程内并发；跨 Collector 实例扩展仍需要 load_balancing 层。v0.160 为速率/字节限制添加了感知 tracestate 的阈值。
drain	components/drain/README.md	处理器	日志	Alpha	对日志正文进行聚类，并为每条记录添加模板。v0.158 用 masking_rules + parameter_key_prefix 替换了 extract_parameters / params_attribute，以处理命名值；并用 emit_wildcards + wildcards_attribute 处理剩余的 <*> 位置。
redaction	components/redaction/README.md	处理器	跟踪、日志、指标	Beta（跟踪）、Alpha（日志/指标）	通过允许列表/阻止列表对敏感属性键和值进行遮蔽或移除，并提供哈希处理和 URL/DB 清理器。
filter	components/filter/README.md	处理器	跟踪、指标、日志、配置文件	Alpha（跟踪/指标/日志）、Development（配置文件）	丢弃符合 OTTL 条件（或旧版指标名称/严重性筛选条件）的 span、指标数据点、日志记录和配置文件。最直接的遥测数据量调节手段。
transform	components/transform/README.md	处理器	跟踪、指标、日志、配置文件	Beta（跟踪/指标/日志）、Development（配置文件）	对 span、指标数据点、日志记录和配置文件原地应用 OTTL 语句进行修改（重命名/脱敏/转换/聚合属性）。OTTL 语言本身位于 otel-ottl 技能中。
probabilistic_sampler	components/probabilistic_sampler/README.md	处理器	跟踪、日志	Beta（跟踪）、Alpha（日志）	头部采样——通过对跟踪 ID（或某个属性）进行哈希，确定性地保留配置百分比的跟踪/日志。它是 tail_sampling 更轻量、无状态的对应工具。
attributes	components/attributes/README.md	处理器	跟踪、指标、日志	Beta	通过有序的操作列表（插入/更新/upsert/删除/哈希/提取/转换）修改 span/日志/数据点的 属性，并限定在包含/排除匹配范围内。
resource	components/resource/README.md	处理器	跟踪、指标、日志、配置文件	Beta（跟踪/指标/日志）、Development（配置文件）	通过与 attributes 相同的操作语法修改遥测的 资源 属性（例如，设置 service.name、删除嘈杂的资源键）。不支持包含/排除匹配。
k8s_attributes	components/k8s_attributes/README.md	处理器	跟踪、指标、日志、配置文件	Stable（跟踪/指标/日志，自 v0.161 起）、Development（配置文件）	为遥测补充 Kubernetes pod/namespace/node/workload 元数据，并通过 IP 或资源属性将每条记录关联到一个 pod。v0.161 默认启用 v1 semconv 门控（单数形式的 k8s.pod.label.*、container.image.tags）。
routing	components/routing/README.md	连接器	跟踪、指标、日志	Alpha	按每种上下文的 OTTL condition/statement 将同一信号的遥测路由到不同管道；使用有序表，匹配第一项生效，未匹配时回退到 default_pipelines。取代已弃用的 routingprocessor。
memory_limiter	components/memory_limiter/README.md	处理器	跟踪、指标、日志、配置文件	Beta（跟踪/指标/日志）、Alpha（配置文件）	防止 OOM 的安全阀：当 Go 堆超出软/硬限制时，通过施加背压拒绝数据。其接收器中间件 扩展 于 v0.158 达到 Beta，但不包含在标准发行版中；捆绑的处理器仍是标准形式。
load_balancing	components/load_balancing/README.md	导出器	跟踪、日志、指标	Beta（跟踪/日志）、Alpha（指标）	通过基于跟踪 ID / service.name /（v0.162+）OTel 随机性的等键构建的一致性哈希环，在下游 Collector 之间分发遥测，将相关记录固定到同一个后端。扩展 tail_sampling/span_metrics 的标准方式。v0.153.0 中从 loadbalancing 重命名而来；保留别名。
otlp（接收器）	components/otlp/README.md	接收器	跟踪、指标、日志、配置文件	Stable（跟踪/指标/日志）、Alpha（配置文件）	标准 OTLP 入口，支持通过 gRPC（4317）和/或 HTTP（4318，protobuf + JSON）接入。必须至少配置一个 protocols: 块。默认端点是 localhost，而不是 0.0.0.0——必须显式设置才能接收容器化流量。
otlp_grpc（导出器）	components/otlp_exporter/README.md	导出器	跟踪、指标、日志、配置文件	Stable（跟踪/指标/日志）、Alpha（配置文件）	通过 gRPC 将 OTLP 发送到下游端点；默认启用 gzip、发送队列和重试。除非启用 pkg.exporterhelper.queueBatchEnabled 门控，否则导出器端的 sending_queue.batch 为可选配置。core v1.50.0 中从 otlp 重命名而来；保留别名。
file_log（接收器）	components/file_log/README.md	接收器	日志	Beta	跟踪日志文件（glob include），将每行/条目转换为日志记录，并通过 stanza operators 管道进行解析。通过指纹和偏移量跟踪应对轮转；使用 storage 持久化偏移量。v0.160 添加了可选的 skip_unmodified_files。
resource_detection	components/resource_detection/README.md	处理器	跟踪、指标、日志、配置文件	Beta（跟踪/指标/日志）、Development（配置文件）	通过有序的 detectors 列表和全局重试设置自动检测资源属性。包含 Azure Container Apps、Azure App Service（v0.160+）和 Azure Functions（v0.162+）检测器。v0.153.0 中从 resourcedetection 重命名而来；保留别名。
file_storage	components/file_storage/README.md	扩展	—（不限定于管道）	Beta	将组件状态持久化到本地磁盘（bbolt），使其在 Collector 重启后仍然保留：接收器读取偏移量（storage:）、导出器持久化发送队列（sending_queue.storage:）以及有状态处理器的决策缓存。每个使用者对应一个 bbolt 文件；除非设置 create_directory: true，否则 directory 必须已存在。它不放在管道中，而是列在 service.extensions: 下，并由其他组件引用。
prometheus（接收器）	components/prometheus/README.md	接收器	指标	Beta	抓取 Prometheus 格式的 HTTP 端点，并将其转换为 OTLP 指标；内嵌 prometheus/prometheus 的抓取管理器——config: 块与 prometheus.yml 使用相同的 YAML（global、scrape_configs、scrape_config_files、服务发现、重新标记）。额外键：trim_metric_suffixes、target_allocator（来自 OTel Operator 的分片目标）、api_server（调试 API）。仅支持抓取：拒绝 remote_write/remote_read/rule_files/告警配置。有状态，不会在多个副本间自动分片。
prometheus（导出器）	components/prometheus_exporter/README.md	导出器	指标	Beta	暴露管道指标供 Prometheus 抓取。内存累加器会在 5m 后过期不再活跃的序列。v0.160 添加了 resource_constant_labels，并弃用 resource_to_telemetry_conversion；add_metric_suffixes 仍已弃用，建议改用 translation_strategy。
prometheus_remote_write（导出器）	components/prometheus_remote_write/README.md	导出器	指标	Beta	将 OTLP 指标作为 Prometheus Remote Write 推送。HTTP 客户端设置嵌套在 http 下；使用 remote_write_queue（而不是 sending_queue）。v0.160 添加了 resource_constant_labels，并弃用 resource_to_telemetry_conversion；RW2 仍需通过门控启用，且仍处于开发阶段。

收集器通用约定

命名实例

每种组件类型都支持 type/name 模式，因此同一类型可以配置多次。管道引用命名形式：

processors:
  log_dedup/health-checks:
    interval: 30s
    conditions:
      - 'log.attributes["log.type"] == "health_check"'
  log_dedup/access-logs:
    interval: 10s

service:
  pipelines:
    logs/health:
      processors: [log_dedup/health-checks]
    logs/access:
      processors: [log_dedup/access-logs]

稳定性级别

组件会针对每种信号发布稳定性级别。推荐用于生产环境时，应将这些级别视为重要依据：

级别	用途
Development	仅用于测试和原型 — 预计会有破坏性变更。
Alpha	用于有限的非关键工作负载 — 配置键仍可能变更。
Beta	可用于生产环境 — 破坏性变更很少。
Stable	用于生产环境 — 保证向后兼容。

现在，稳定性因组件而异；对于多信号组件，还会因信号而异（例如，redaction 对 traces 为 Beta，对 logs/metrics 为 Alpha）。不要假设索引集合中的组件都只有一个稳定性级别：请查看每个组件 README 标头中的元数据表，以确认权威稳定性级别；用户询问是否适合用于生产环境时，应明确说明该级别。

最近的重命名

自 v0.146.0 起，许多组件已重命名为 snake_case，重命名工作仍在进行（例如，awss3 接收器在 v0.162.0 中更名为 aws_s3，sqlserver 在 v0.163.0 中更名为 sql_server；同一家族的接收器和导出器会分别重命名，因此请检查组件 metadata.yaml 中的 type）。旧名称仍作为弃用别名保留 — 旧配置仍可使用，但新配置应使用新名称。标记配置已失效之前，请查阅上游组件 README，确认确切的重命名版本。

示例：logdedup → log_dedup、hostmetrics → host_metrics、spanmetrics → span_metrics、servicegraph → service_graph、k8sattributes → k8s_attributes，以及若干 _log 和 _check 接收器。

管道位置

适用于各组件的两条经验法则：

• 在任何处理器列表中，memory_limiter 都应放在最前面，位于所有会分配缓冲区的组件之前（log_dedup、transform、tail_sampling 等）。
• otlp_grpc 导出器的发送队列默认启用，但其 sending_queue.batch 子块需选择启用。请明确启用导出器端批处理（或启用 alpha pkg.exporterhelper.queueBatchEnabled 迁移开关）。独立的 batch 处理器仍处于 Beta 阶段且受支持；需要在管道级别批处理时使用它，并将其放在数据丢弃处理器之后。

验证测试框架

每个组件页面的 Verification 部分都提供配置、telemetrygen 命令和预期输出。运行任意示例的步骤如下：

1. 将 YAML 保存到文件，并启动包含该组件的收集器 — 对于 contrib/k8s 发行版中的组件，运行 otelcol-contrib --config <file>.yaml；对于不属于任何发行版的组件，请先使用 OpenTelemetry Collector Builder (OCB) 构建自定义收集器。
2. 使用 telemetrygen 发送遥测数据（参见 otel-telemetrygen skill）。
3. 查看 debug 导出器的标准输出（或 file 导出器的输出），确认预期结果。

Verification 配置是最小复现示例：它们有意省略 memory_limiter 和其他生产环境所需的基础配置，以便隔离被测组件。请勿原样复制到生产环境中。

向此技能添加新组件

扩展覆盖范围时：

1. 创建目录 components/<type>/。 文件不带 frontmatter——只有 SKILL.md 带 frontmatter。
2. 编写精简的 README.md——始终加载，并保持简短：
   • 头部元数据表——包含类型、type 名称、信号、各信号的稳定性、发行版、Go 模块、上游 README 链接，以及组件曾重命名时的重命名说明。
   • 描述——用 1–2 段简洁地说明组件的功能和机制（将详细机制和参考资料放入 configuration.md）。
   • 主要使用场景——“适用情况”/“不适用情况”。
   • 相关组件——交叉链接。
   • 详情索引——项目符号列表，每项链接到一个详情文件，后接破折号和简短的内容说明（例如 - [Configuration](configuration.md) — config keys, defaults, validation），让读者只加载问题所需的内容。
3. 将其余内容拆分到同一目录下、按需加载的详情文件中：
   • configuration.md——完整的配置参考表（键、类型、默认值、验证），以及任何机制/参考表。
   • verification.md——提供一个 telemetrygen + debug/file 导出器方案，以证明文档所述行为；交叉引用 otel-telemetrygen 技能。**逐一核实每个 telemetrygen 标志是否存在于该技能中——切勿声称存在不存在的标志。**如果 telemetrygen 无法生成组件所需的输入，请说明这一点并指出替代方案（OTTL/transform、自定义生成器）。保持配置为最简复现（参见 Verification harness）。
   • advanced.md——命名实例、多管道配置、组合用法和边缘配置。
   • quirks.md——注意事项、稳定性提示、内存模型、验证错误→修复表、反模式和故障排查。
   • 当某个较大的部分内容很多时，将其拆分到独立文件中（例如，将大型策略目录放入 policies.md）；较短的部分则合并到同级文件中，不要创建空壳文件。更新任何因跨文件而失效的页内锚点链接。
4. 将 components/log_dedup/ 和 components/interval/ 用作此结构的参考实现。
5. 在上方的 Component index 中添加一行（File 列指向 components/<type>/README.md）。
6. 如果新组件引入了明显独特的用户关键词，请更新此文件 frontmatter 中的描述触发短语。