Otel 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 otel-ottl), declarative SDK configuration (otel-declarative-config), deploying the eBPF profiler or other profiles producers (otel-profiles), or end-to-end pipeline design choices. Reach for those skills when the question is about transformation language, SDK setup, or pipeline composition.

Workflow

1. Identify the component. Find the type in the user's config or question (log_dedup, interval, otlp, …). Note that many components have been renamed to snake_case since v0.146.0 with deprecated aliases preserved — see Recent renames.
2. Load the component page before answering. If the component is in the Component index, always read components/<type>/README.md 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 configuration.md for versioned keys, defaults, or validation; quirks.md for 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.
3. If the component is not indexed, say so explicitly and fall back to the upstream README under processor/<name>/, receiver/<name>/, exporter/<name>/, connector/<name>/, or extension/<name>/ in opentelemetry-collector-contrib. Don't invent config keys from memory — Collector components evolve quickly.
4. Apply Collector-wide conventions. Named instances (type/name), stability levels, and pipeline placement rules in Collector-wide conventions apply to every component.
5. Verify. Run the component page's Verification recipe — telemetrygen (see the otel-telemetrygen skill) plus a debug or file exporter — 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.

Component index

Each component is a directory under components/<type>/. The File column points at the lean README.md (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.

Coverage is intentionally selective. If a component is not indexed here, fall back to the upstream component README for the user's Collector version.

Verified 2026-10-25: Stability cells here and in component README headers match metadata.yaml at core and contrib v0.163.0; rename and "since" versions match metadata.yaml at the named tag and the one before. Offline, cite that release and date, not current stability.

Collector-wide conventions

Named instances

Every component type supports the type/name pattern so the same type can be configured more than once. The pipeline references the named form:

yamlCopy code
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:

Stability now varies per component — and per signal for multi-signal components (e.g. redaction 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.

Recent renames

Many components have been renamed to snake_case since v0.146.0, and renames are still landing (e.g. the awss3 receiver → aws_s3 in v0.162.0, sqlserver → sql_server in v0.163.0; receivers and exporters of one family rename separately, so check the component's metadata.yaml type). 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: logdedup → log_dedup, hostmetrics → host_metrics, spanmetrics → span_metrics, servicegraph → service_graph, k8sattributes → k8s_attributes, plus several _log and _check receivers.

Pipeline placement

Two rules of thumb that apply across components:

• memory_limiter belongs first in any processor list, before anything that allocates buffers (log_dedup, transform, tail_sampling, …).
• The otlp_grpc exporter's sending queue is enabled by default, but its sending_queue.batch sub-block is opt-in. Enable exporter-side batching explicitly (or with the alpha pkg.exporterhelper.queueBatchEnabled migration gate). The separate batch processor remains Beta and supported; use it when pipeline-level batching is needed and place it after data-dropping processors.

Verification harness

Each component page's Verification section gives a config, a telemetrygen command, and the expected output. To run any of them:

1. Save the YAML to a file and start a collector that bundles the component — for components in the contrib/k8s distributions, otelcol-contrib --config <file>.yaml; for components not in any distribution, build a custom collector with the OpenTelemetry Collector Builder (OCB) first.
2. Send telemetry with telemetrygen (see the otel-telemetrygen skill).
3. Watch the debug exporter's stdout (or the file exporter's output) for the expected result.

The Verification configs are minimal repros: they omit memory_limiter and other production scaffolding on purpose, to isolate the component under test. Don't copy them verbatim into production.

Adding a new component to this skill

When extending coverage:

1. Create the directory components/<type>/. Files carry no frontmatter — only SKILL.md has frontmatter.
2. Write a lean README.md — always loaded, kept small:
   • Header metadata table — kind, type name, signals, per-signal stability, distributions, Go module, upstream README link, and a rename note if the component was renamed.
   • 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. - [Configuration](configuration.md) — config keys, defaults, validation), so the reader loads only what a question needs.
3. Split the rest into on-demand detail files under the same directory:
   • configuration.md — full config-reference table (key, type, default, validation) plus any mechanism/reference tables.
   • verification.md — a telemetrygen + debug/file exporter recipe that proves the documented behavior; cross-reference the otel-telemetrygen skill. Verify every telemetrygen flag against that skill — never assert a flag that doesn't exist. If telemetrygen can't produce the input the component needs, say so and point to an alternative (OTTL/transform, a custom emitter). Keep the config a minimal repro (see Verification harness).
   • advanced.md — named instances, multi-pipeline setups, combinations, and edge configs.
   • quirks.md — gotchas, stability caveats, memory model, a validation-error→fix table, anti-patterns, and troubleshooting.
   • Split a heavy section into its own file when it's large (e.g. policies.md 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.
4. Use components/log_dedup/ and components/interval/ as reference implementations of this structure.
5. Add a row to the Component index above (the File column points at components/<type>/README.md).
6. Update the description trigger phrases in this file's frontmatter if the new component introduces a clearly distinct user-facing keyword.