otel-collector
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseOpenTelemetry Collector
OpenTelemetry Collector
This skill covers the configuration surface of individual OpenTelemetry Collector components. It targets opentelemetry-collector and opentelemetry-collector-contrib.
It does not cover OTTL expressions (see ), declarative SDK configuration (), or end-to-end pipeline design choices. Reach for those skills when the question is about transformation language, SDK setup, or pipeline composition.
otel-ottlotel-declarative-config本技能涵盖单个OpenTelemetry Collector组件的配置内容，针对opentelemetry-collector和opentelemetry-collector-contrib项目。
本技能不覆盖OTTL表达式（详见技能）、声明式SDK配置（）或端到端管线设计选择。若问题涉及转换语言、SDK设置或管线组合，请使用对应技能。
otel-ottlotel-declarative-configWorkflow
工作流程
- Identify the component. Find the in the user's config or question (
type,log_dedup,interval, …). Note that several components were renamed to snake_case across v0.146.0–v0.154.0 with deprecated aliases preserved — see Recent renames.otlp - Load the component page before answering. If the component is in the Component index, always read first — the top-level index is only a routing aid, not enough evidence for an answer. Follow its Details index to the smallest relevant file: read
components/<type>/README.mdfor versioned keys, defaults, or validation;configuration.mdfor stability, availability, failure behavior, or migration traps; and the other detail files only as the question requires. Do not infer exact configuration or status from the summary row or memory.quirks.md - If the component is not indexed, say so explicitly and fall back to the upstream README under ,
processor/<name>/,receiver/<name>/,exporter/<name>/, orconnector/<name>/in opentelemetry-collector-contrib. Don't invent config keys from memory — Collector components evolve quickly.extension/<name>/ - Apply Collector-wide conventions. Named instances (), stability levels, and pipeline placement rules in Collector-wide conventions apply to every component.
type/name - Verify. Run the component page's Verification recipe — (see the
telemetrygenskill) plus aotel-telemetrygenordebugexporter — to confirm the component behaves as the docs claim. Alpha- and Development-stability components are common here, and behavior changes between releases. See Verification harness for how to run a recipe end-to-end.file
- 识别组件：从用户的配置或问题中找到字段（如
type、log_dedup、interval等）。注意在v0.146.0–v0.154.0版本期间，多个组件被重命名为蛇形命名（snake_case），同时保留了旧名称作为已弃用的别名——详见近期重命名。otlp - 加载组件页面后再作答：若组件在组件索引中，务必先阅读——顶层索引仅作为导航辅助，不足以作为回答依据。按照其详情索引找到最相关的细分文件：查看
components/<type>/README.md获取版本化配置键、默认值或验证规则；查看configuration.md获取稳定性、可用性、故障行为或迁移陷阱信息；其他详情文件仅在问题需要时查阅。不要从摘要行或记忆中推断准确的配置或状态。quirks.md - 若组件未被索引：明确告知用户，并参考opentelemetry-collector-contrib中、
processor/<name>/、receiver/<name>/、exporter/<name>/或connector/<name>/下的上游README文档。不要凭记忆编造配置键——Collector组件迭代速度很快。extension/<name>/ - 应用Collector全局约定：命名实例（）、稳定性级别和管线放置规则等Collector全局约定适用于所有组件。
type/name - 验证：运行组件页面的验证方案——使用（详见
telemetrygen技能）搭配otel-telemetrygen或debug导出器——确认组件行为与文档描述一致。Alpha和Development稳定性级别的组件很常见，且不同版本间行为可能变化。详见验证工具了解如何端到端运行方案。file
Component index
组件索引
Each component is a directory under . The column points at the lean (metadata, description, main use-cases, and a Details index); the full config reference, verification recipe, advanced use-cases, and quirks live in on-demand detail files linked from that README.
components/<type>/FileREADME.mdCoverage is intentionally selective. If a component is not indexed here, fall back to the upstream component README for the user's Collector version.
| Type | File | Kind | Signals | Stability | Summary |
|---|---|---|---|---|---|
| | processor | logs | Alpha | Deduplicates identical log records over a time window; emits one aggregated log with a count. Renamed from |
| | processor | metrics | Alpha | Buffers cumulative monotonic metrics (and optionally gauges/summaries) and emits the latest value once per interval. Delta and non-monotonic sums pass through unchanged. |
| | processor | traces | Beta | Buffers whole traces and makes a single keep/drop decision after a wait window via policies. Requires a |
| | processor | logs | Alpha | Clusters log bodies and annotates each record with a template. v0.158 replaced |
| | processor | traces, logs, metrics | Beta (traces), Alpha (logs/metrics) | Allow/block-list masking or removal of sensitive attribute keys and values, with hashing and URL/DB sanitizers. |
| | processor | traces, metrics, logs, profiles | Alpha (traces/metrics/logs), Development (profiles) | Drops spans, metric data points, log records, and profiles that match OTTL conditions (or legacy metric-name / severity filters). The most direct telemetry-volume lever. |
| | processor | traces, metrics, logs, profiles | Beta (traces/metrics/logs), Development (profiles) | Applies OTTL statements to mutate spans, metric data points, log records, and profiles in place (rename/redact/convert/aggregate attributes). The OTTL language itself lives in the |
| | processor | traces, logs | Beta (traces), Alpha (logs) | Head sampling — deterministically keeps a configured percentage of traces/logs by hashing the trace ID (or an attribute). The cheaper, stateless counterpart to |
| | processor | traces, metrics, logs | Beta | Modifies span/log/datapoint attributes via an ordered action list (insert/update/upsert/delete/hash/extract/convert), scoped by include/exclude matching. |
| | processor | traces, metrics, logs, profiles | Beta (traces/metrics/logs), Development (profiles) | Modifies the resource attributes of telemetry via the same action grammar as |
| | processor | traces, metrics, logs, profiles | Beta (traces/metrics/logs), Development (profiles) | Enriches telemetry with Kubernetes pod/namespace/node/workload metadata, associating each record to a pod by IP or resource attribute. Renamed from |
| | connector | traces, metrics, logs | Alpha | Routes same-signal telemetry to different pipelines by OTTL |
| | processor | traces, metrics, logs, profiles | Beta (traces/metrics/logs), Alpha (profiles) | Safety valve against OOM: refuses data with backpressure when Go heap exceeds a soft/hard limit. Its receiver-middleware extension reached Beta in v0.158 but is absent from stock distributions; the bundled processor remains the standard form. |
| | exporter | traces, logs, metrics | Beta (traces/logs), Development (metrics) | Distributes telemetry across downstream Collectors via a consistent-hash ring keyed on trace ID / |
| | receiver | traces, metrics, logs, profiles | Stable (traces/metrics/logs), Alpha (profiles) | The canonical OTLP ingress over gRPC ( |
| | exporter | traces, metrics, logs, profiles | Stable (traces/metrics/logs), Alpha (profiles) | Sends OTLP over gRPC to a downstream endpoint; gzip by default. Built-in |
| | receiver | logs | Beta | Tails log files (glob |
| | processor | traces, metrics, logs, profiles | Beta (traces/metrics/logs), Development (profiles) | Auto-detects resource attributes via an ordered |
| | extension | — (not pipeline-scoped) | Beta | Persists component state to local disk (bbolt) so it survives a Collector restart: receiver read offsets ( |
| | receiver | metrics | Beta | Scrapes Prometheus-format HTTP endpoints and converts them to OTLP metrics, embedding |
| | exporter | metrics | Beta | Exposes pipeline metrics in Prometheus exposition format on a |
| | exporter | metrics | Beta | Pushes OTLP metrics as Prometheus Remote Write. v0.158 added |
每个组件对应下的一个目录。列指向精简版（包含元数据、描述、主要用例和详情索引）；完整的配置参考、验证方案、高级用例和注意事项存放在该README链接的按需加载详情文件中。
components/<type>/FileREADME.md覆盖范围为选择性收录。若组件未在此索引中，请根据用户使用的Collector版本参考上游组件README。
| 类型 | 文件 | 类别 | 信号 | 稳定性 | 摘要 |
|---|---|---|---|---|---|
| | processor | logs | Alpha | 在时间窗口内对重复的日志记录进行去重；生成一条包含计数的聚合日志。在v0.151.0版本中从 |
| | processor | metrics | Alpha | 缓冲累积单调指标（可选包含仪表盘/摘要），并按指定间隔输出最新值。增量和非单调求和数据直接通过。 |
| | processor | traces | Beta | 缓冲完整链路，并在等待窗口后通过策略做出保留/丢弃的单一决策。需要 |
| | processor | logs | Alpha | 聚类日志内容，并为每条记录添加模板注释。v0.158版本用 |
| | processor | traces, logs, metrics | Beta（traces）, Alpha（logs/metrics） | 通过允许/阻止列表屏蔽或移除敏感属性键和值，支持哈希、URL/DB清理功能。 |
| | processor | traces, metrics, logs, profiles | Alpha（traces/metrics/logs）, Development（profiles） | 丢弃符合OTTL条件（或旧版指标名称/严重度过滤器）的链路、指标数据点、日志记录和性能剖析数据。是最直接的遥测流量控制工具。 |
| | processor | traces, metrics, logs, profiles | Beta（traces/metrics/logs）, Development（profiles） | 应用OTTL语句原地修改链路、指标数据点、日志记录和性能剖析数据（重命名/脱敏/转换/聚合属性）。OTTL语言本身属于 |
| | processor | traces, logs | Beta（traces）, Alpha（logs） | 头部采样——通过哈希链路ID（或属性）确定性地保留指定比例的链路/日志。是 |
| | processor | traces, metrics, logs | Beta | 通过有序动作列表（插入/更新/插入更新/删除/哈希/提取/转换）修改链路/日志/数据点的属性，可通过包含/排除规则限定范围。 |
| | processor | traces, metrics, logs, profiles | Beta（traces/metrics/logs）, Development（profiles） | 通过与 |
| | processor | traces, metrics, logs, profiles | Beta（traces/metrics/logs）, Development（profiles） | 为遥测补充Kubernetes Pod/命名空间/节点/工作负载元数据，通过IP或资源属性将每条记录关联到对应的Pod。在v0.146.0版本中从 |
| | connector | traces, metrics, logs | Alpha | 通过每个上下文的OTTL |
| | processor | traces, metrics, logs, profiles | Beta（traces/metrics/logs）, Alpha（profiles） | 防止内存溢出的安全阀门：当Go堆内存超过软/硬限制时，通过背压拒绝接收数据。其接收器中间件扩展在v0.158版本达到Beta级别，但未包含在标准发行版中；捆绑的processor仍是标准形式。 |
| | exporter | traces, logs, metrics | Beta（traces/logs）, Development（metrics） | 通过基于链路ID/ |
| | receiver | traces, metrics, logs, profiles | Stable（traces/metrics/logs）, Alpha（profiles） | 标准的OTLP入口，支持gRPC（ |
| | exporter | traces, metrics, logs, profiles | Stable（traces/metrics/logs）, Alpha（profiles） | 通过gRPC将OTLP数据发送到下游端点；默认启用gzip压缩。内置 |
| | receiver | logs | Beta | 追踪日志文件（支持通配符 |
| | processor | traces, metrics, logs, profiles | Beta（traces/metrics/logs）, Development（profiles） | 通过有序的 |
| | extension | —（不属于管线范围） | Beta | 将组件状态持久化到本地磁盘（bbolt），使其在Collector重启后仍保留：接收器读取偏移量（ |
| | receiver | metrics | Beta | 抓取Prometheus格式的HTTP端点并转换为OTLP指标，嵌入 |
| | exporter | metrics | Beta | 在 |
| | exporter | metrics | Beta | 将OTLP指标以Prometheus Remote Write格式推送。v0.158版本新增 |
Collector-wide conventions
Collector全局约定
Named instances
命名实例
Every component type supports the pattern so the same type can be configured more than once. The pipeline references the named form:
type/nameyaml
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]所有组件类型都支持模式，以便同一类型可配置多个实例。管线中引用命名形式：
type/nameyaml
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]Stability levels
稳定性级别
Components publish a stability level per signal. Treat these as load-bearing when recommending production use:
| Level | Use in |
|---|---|
| Development | Tests and prototypes only — breaking changes expected. |
| Alpha | Limited, non-critical workloads — config keys can still change. |
| Beta | Production viable — breaking changes rare. |
| Stable | Production — backward compatibility guaranteed. |
Stability now varies per component — and per signal for multi-signal components (e.g. is Beta for traces but Alpha for logs/metrics). Don't assume a single level for the indexed set: check each component's README header metadata table for the authoritative stability and surface it when the user asks about production readiness.
redaction组件按信号发布稳定性级别。建议在推荐生产使用时严格遵循：
| 级别 | 使用场景 |
|---|---|
| Development | 仅用于测试和原型——可能存在破坏性变更。 |
| Alpha | 有限的非关键工作负载——配置键仍可能变更。 |
| Beta | 适用于生产环境——破坏性变更极少。 |
| Stable | 生产环境——保证向后兼容性。 |
稳定性现在因组件而异——多信号组件的稳定性还因信号不同而不同（例如对traces是Beta级别，对logs/metrics是Alpha级别）。不要假设所有索引组件的稳定性级别一致：当用户询问生产就绪性时，需查看每个组件README头部的元数据表获取权威的稳定性信息并告知用户。
redactionRecent renames
近期重命名
Many components were renamed to snake_case across v0.146.0–v0.154.0. The legacy names remain as deprecated aliases — old configs keep working but new configs should use the new names. Check the upstream component README for the exact rename version before flagging a config as broken.
Examples: → , → , → , → , → , plus several and receivers.
logdeduplog_deduphostmetricshost_metricsspanmetricsspan_metricsservicegraphservice_graphk8sattributesk8s_attributes_log_check在v0.146.0–v0.154.0版本期间，许多组件被重命名为蛇形命名（snake_case）。旧名称仍作为已弃用的别名保留——旧配置仍可正常工作，但新配置应使用新名称。在标记配置为无效前，请先查看上游组件README确认具体的重命名版本。
示例： → 、 → 、 → 、 → 、 → ，以及多个和接收器。
logdeduplog_deduphostmetricshost_metricsspanmetricsspan_metricsservicegraphservice_graphk8sattributesk8s_attributes_log_checkPipeline placement
管线放置
Two rules of thumb that apply across components:
- belongs first in any processor list, before anything that allocates buffers (
memory_limiter,log_dedup,transform, …).tail_sampling - The exporter's
otlp_grpcis enabled by default. The separatesending_queue.batchprocessor remains Beta and supported; use it when pipeline-level batching is needed, place it after data-dropping processors, and avoid unintentional double batching when an exporter already batches.batch
适用于所有组件的两条经验法则：
- 应放在processor列表的首位，在任何会分配缓冲区的组件（如
memory_limiter、log_dedup、transform等）之前。tail_sampling - 导出器的
otlp_grpc默认启用。单独的sending_queue.batchprocessor仍为Beta级别且受支持；当需要管线级批处理时使用它，将其放在数据丢弃类processor之后，当导出器已支持批处理时避免无意的双重批处理。batch
Verification harness
验证工具
Each component page's Verification section gives a config, a command, and the expected output. To run any of them:
telemetrygen- Save the YAML to a file and start a collector that bundles the component — for components in the /
contribdistributions,k8s; for components not in any distribution, build a custom collector with the OpenTelemetry Collector Builder (OCB) first.otelcol-contrib --config <file>.yaml - Send telemetry with (see the
telemetrygenskill).otel-telemetrygen - Watch the exporter's stdout (or the
debugexporter's output) for the expected result.file
The Verification configs are minimal repros: they omit and other production scaffolding on purpose, to isolate the component under test. Don't copy them verbatim into production.
memory_limiter每个组件页面的验证部分提供了配置、命令和预期输出。运行任意方案的步骤：
telemetrygen- 将YAML保存到文件并启动包含该组件的Collector——对于/
contrib发行版中的组件，使用k8s；对于未包含在任何发行版中的组件，先使用OpenTelemetry Collector Builder (OCB)构建自定义Collector。otelcol-contrib --config <file>.yaml - 使用发送遥测数据（详见
telemetrygen技能）。otel-telemetrygen - 查看导出器的标准输出（或
debug导出器的输出）确认预期结果。file
验证配置是最小复现示例：为了隔离测试组件，刻意省略了和其他生产环境脚手架。不要直接复制到生产环境中使用。
memory_limiterAdding a new component to this skill
向本技能添加新组件
When extending coverage:
- Create the directory . Files carry no frontmatter — only
components/<type>/has frontmatter.SKILL.md - Write a lean — always loaded, kept small:
README.md- Header metadata table — kind, name, signals, per-signal stability, distributions, Go module, upstream README link, and a rename note if the component was renamed.
type - Description — what the component does and the mechanism, in 1–2 tight paragraphs (push detailed mechanism/reference into ).
configuration.md - Main use-cases — "Use when" / "Avoid when".
- Related components — cross-links.
- Details index — a bullet list where each item links a detail file followed by an em dash and a short description of its contents (e.g. ), so the reader loads only what a question needs.
- [Configuration](configuration.md) — config keys, defaults, validation
- Header metadata table — kind,
- Split the rest into on-demand detail files under the same directory:
- — full config-reference table (key, type, default, validation) plus any mechanism/reference tables.
configuration.md - — a
verification.md+telemetrygen/debugexporter recipe that proves the documented behavior; cross-reference thefileskill. Verify everyotel-telemetrygenflag against that skill — never assert a flag that doesn't exist. Iftelemetrygencan't produce the input the component needs, say so and point to an alternative (OTTL/telemetrygen, a custom emitter). Keep the config a minimal repro (see Verification harness).transform - — named instances, multi-pipeline setups, combinations, and edge configs.
advanced.md - — gotchas, stability caveats, memory model, a validation-error→fix table, anti-patterns, and troubleshooting.
quirks.md - Split a heavy section into its own file when it's large (e.g. for a big policy catalog); merge trivial sections into a sibling rather than create a stub. Repoint any in-page anchor links that now cross files.
policies.md
- Use and
components/log_dedup/as reference implementations of this structure.components/interval/ - Add a row to the Component index above (the column points at
File).components/<type>/README.md - Update the description trigger phrases in this file's frontmatter if the new component introduces a clearly distinct user-facing keyword.
扩展覆盖范围时：
- 创建目录。文件无需前置内容——仅
components/<type>/包含前置内容。SKILL.md - 编写精简版——始终加载，保持内容简洁：
README.md- 头部元数据表——类别、名称、信号、按信号划分的稳定性、发行版、Go模块、上游README链接，以及组件重命名说明（若有）。
type - 描述——组件功能和机制，1-2段简洁文字（将详细机制/参考内容放到中）。
configuration.md - 主要用例——"适用场景" / "避免场景"。
- 相关组件——交叉链接。
- 详情索引——项目符号列表，每个条目链接到详情文件，后跟短横线和内容描述（例如），以便读者仅加载问题所需内容。
- [配置](configuration.md) — 配置键、默认值、验证规则
- 头部元数据表——类别、
- 将剩余内容拆分为按需加载的详情文件，放在同一目录下：
- ——完整的配置参考表（键、类型、默认值、验证规则）及任何机制/参考表。
configuration.md - ——
verification.md+telemetrygen/debug导出器的验证方案，用于验证文档描述的行为；交叉引用file技能。**务必对照该技能验证每个otel-telemetrygen参数——切勿断言不存在的参数。**若telemetrygen无法生成组件所需的输入，请明确说明并指向替代方案（OTTL/telemetrygen、自定义发射器）。保持配置为最小复现示例（详见验证工具）。transform - ——命名实例、多管线设置、组合方式和边缘配置。
advanced.md - ——注意事项、稳定性警告、内存模型、验证错误→修复表、反模式和故障排除。
quirks.md - 当某部分内容较多时，将其拆分为独立文件（例如大型策略目录的）；将琐碎内容合并到相邻文件中，避免创建空文件。更新所有现在跨文件的页内锚点链接。
policies.md
- 以和
components/log_dedup/作为结构参考实现。components/interval/ - 在上方的组件索引中添加一行（列指向
File）。components/<type>/README.md - 若新组件引入了明显独特的用户可见关键词，请更新本文件前置内容中的描述触发短语。",