{{ analysis.summaryTitle }}
{{ analysis.primary }}
{{ analysis.summaryLine }}
{{ badge.label }}
Start from a common Collector shape, then adjust endpoints and safeguards for your rollout.
Enable the telemetry signal types this Collector should receive and export.
Choose which OTLP protocols the generated receiver exposes.
Bind to the narrowest address that still lets your clients reach the Collector.
Pick the destination type emitted in every selected pipeline.
{{ exporterEndpointHint }}
Use verified TLS for production and insecure only for trusted local test endpoints.
Choose how the memory_limiter processor sizes the Collector heap limit.
Percent of available memory targeted by memory_limiter.
%
Percent reserved between the memory soft and hard limits.
%
Hard memory limit for memory_limiter.
MiB
Expected short-term memory spike between checks.
MiB
OpenTelemetry duration such as 1s or 500ms.
OpenTelemetry duration such as 200ms, 1s, or 5s.
Number of spans, metric points, or log records that triggers a send.
Use 0 to omit send_batch_max_size.
Adds sending_queue.enabled for OTLP exporters so temporary backend stalls can buffer briefly.
Adds retry_on_failure.enabled for transient remote exporter failures.
One key=value attribute per line, for example deployment.environment=prod.
Leave blank unless your backend requires a header such as Authorization.
Adds health_check and enables it under service.extensions.
Useful for local troubleshooting; expose carefully in shared environments.
Adds zpages for live diagnostic views during development or incident debugging.
Choose the Collector's internal log verbosity.
basic is safer for routine smoke tests; detailed prints more telemetry payload content.
{{ analysis.yaml }}
SignalPipelineReceiversProcessor orderExportersRollout noteCopy
{{ row.signal }} {{ row.pipeline }} {{ row.receivers }} {{ row.processors }} {{ row.exporters }} {{ row.note }}
SeverityCheckFindingActionCopy
{{ row.severity }} {{ row.check }} {{ row.finding }} {{ row.action }}
Tags: Automation, Devops
Export to PDF Fullscreen
Customize
Advanced
:

OpenTelemetry Collector configuration describes how telemetry enters a Collector, how it is handled inside the process, and where it is sent next. A small YAML mistake can leave traces, metrics, or logs without an active pipeline, point clients at the wrong OTLP endpoint, or remove memory protection from a busy deployment.

The Collector works as a vendor-neutral hop between instrumented services and observability backends. Its configuration usually declares receivers, processors, exporters, extensions, and a service section that activates the selected pipelines. That structure is compact, but it is easy to mix transport details, processor order, endpoint syntax, and rollout safeguards when a team is preparing an agent, gateway, or local debug Collector.

Diagram showing OTLP receivers feeding ordered processors, exporters, and service pipelines for traces, metrics, and logs.

A generated Collector file is a starting point for review, not proof that a deployment is ready. Each Collector distribution decides which components are available, and each environment decides whether an endpoint, TLS setting, auth header, memory budget, or diagnostic extension is safe to expose. The safest rollout pairs generated YAML with distribution-specific validation and a small traffic test before changing production ingestion.

Technical Details:

An OpenTelemetry Collector pipeline is activated only when configured components are referenced from the service pipelines section. Declaring a receiver, processor, exporter, or extension by itself is not enough. Traces, metrics, and logs each need a signal pipeline that names the receiver list, ordered processor list, and exporter list to use for that signal.

OTLP uses separate common defaults for its two transports. OTLP/gRPC normally listens on port 4317, while OTLP/HTTP normally listens on port 4318. A gRPC exporter endpoint is typically written as host:port. An OTLP HTTP exporter uses an HTTP or HTTPS base URL, with signal-specific paths handled by the protocol behavior rather than typed into this config.

Processor order changes Collector behavior. The memory limiter belongs early because it can refuse data and let receivers apply backpressure before downstream processors allocate more memory. Resource enrichment can add common attributes after that, and batching is usually placed later so data drops, memory checks, and enrichment happen before records are grouped for export.

Rule Core

The generated YAML follows a fixed component path. Optional settings change which components appear, but the service pipelines still connect the same component classes.

Config area Generated rule Why it matters
receivers.otlp Creates OTLP gRPC on bind:4317, OTLP HTTP on bind:4318, or both. Client SDKs and agents must send to a listener that actually exists.
processors Emits memory_limiter when enabled, optional resource/common, and batch for every selected signal. The processor sequence controls memory pressure, common attributes, and export batching.
exporters Emits otlp, otlphttp, debug, or otlp plus debug based on the selected target. The selected exporter decides whether telemetry goes to a remote backend, local debug output, or both.
extensions Adds health_check, pprof, and zpages only when their switches are enabled. Diagnostics can help rollout checks, but they also expose endpoints that need careful network placement.
service.pipelines Creates one pipeline for each enabled signal among traces, metrics, and logs. At least one signal must be enabled, and each referenced component must support that signal in the chosen distribution.

The memory limiter has two sizing modes. Percentage mode targets a share of available host or container memory. Fixed mode writes explicit MiB values. In both cases the spike setting reserves the gap between the soft limit and the hard limit; if traffic can grow faster than that gap between checks, the process can still cross the hard limit temporarily.

Check Boundary Result meaning
Signal coverage At least one of traces, metrics, or logs must be enabled. No signal means the service section has no useful telemetry pipeline.
Endpoint syntax OTLP gRPC rejects URL schemes, while OTLP HTTP expects http:// or https://. Wrong syntax can make a valid-looking YAML file fail during Collector validation.
Memory spike Spike percentage must be below limit percentage, and fixed spike MiB must be below fixed limit MiB. The soft limit must remain below the hard limit.
Batch size send_batch_max_size is omitted at 0; otherwise it must be at least send_batch_size. The max setting splits large batches only when an upper bound is requested.
Resource attributes Each non-comment line must use key=value, with keys limited to letters, numbers, dots, dashes, and underscores. Bad attribute lines block readiness rather than producing ambiguous enrichment.
Auth header A remote exporter header needs both a token-safe header name and a value. Half-entered credentials are caught before the YAML is copied.

The batch processor uses timeout and send_batch_size as send triggers. The size trigger is not a hard cap. A positive send_batch_max_size is needed when the next component or backend requires an upper batch size. Remote exporters can also include a sending queue and retry flag, which gives the Collector a better chance to ride through short backend stalls without immediately dropping telemetry.

Everyday Use & Decision Guide:

Start from the preset closest to the deployment shape. Edge agent to OTLP gateway fits a host or sidecar collector that forwards all three signals to a gRPC gateway. Gateway to OTLP HTTP backend widens the receiver bind address and prepares a vendor-style HTTPS exporter. Local debug collector keeps output local to the debug exporter, while Logs pipeline to OTLP HTTP narrows the service section to logs.

Use localhost when producers run on the same host and no remote clients need to connect. Choose 0.0.0.0 only when a container, pod, or network service must accept traffic from elsewhere, then place the Collector behind the intended service, firewall, or authentication control. The audit row for Receiver exposure is the main stop-and-check cue for this decision.

  • Choose gRPC and HTTP when clients may use either OTLP transport. Pick one protocol when the sender fleet is known.
  • Use Verified TLS for ordinary remote OTLP gRPC export. Use Insecure / local plaintext only for trusted local endpoints.
  • Keep Memory guard enabled for production-like traffic. Turning it off is best reserved for small local smoke tests.
  • Use environment references in Exporter auth header values instead of literal secrets.
  • Add Resource attributes only for stable deployment-wide values, such as environment or namespace.
  • Enable pprof and zpages only when diagnostic access is intentionally exposed and protected.

The most useful first result is the summary line. It names the selected signals, OTLP protocols, processor sequence, and exporter target. Then read Pipeline Ledger to confirm every enabled signal uses the expected receiver, processor order, and exporter list. Config Audit is the review checklist before copying the YAML into a real Collector.

A clean readiness state does not mean the config will load in every Collector distribution. Run the generated YAML through otelcol validate --config collector.yaml with the same Collector binary or container image that will run it, then send a small trace, metric, or log sample before widening traffic.

Step-by-Step Guide:

Build the config from the traffic path first, then tune safeguards and diagnostics.

  1. Select Config preset. The form updates the signal switches, receiver protocols, exporter type, memory mode, and common advanced defaults.
  2. Confirm Signal pipelines. If all three switches are off, the summary changes to Needs input and the error list asks for at least one pipeline.
  3. Set OTLP receiver protocols and Receiver bind address. Use the audit row to catch unintended 0.0.0.0 exposure.
  4. Choose Exporter target. For OTLP gRPC, enter a host:port endpoint. For OTLP HTTP, enter an HTTP or HTTPS base URL.
  5. Set Exporter security for gRPC exporters. If a backend requires a header, open Advanced and fill both header fields.
  6. Choose Memory guard. In percentage mode, keep the spike percentage below the limit percentage. In fixed mode, keep the spike MiB below the hard limit.
  7. Review Batch timeout, Batch send size, and Max batch size. If the max is positive and below the send size, the error list blocks readiness.
  8. Add resource attributes and diagnostic extensions only when they match the rollout plan, then read Config Audit for warnings about memory, listeners, buffering, or debug output.
  9. Use Collector YAML for the config text, Pipeline Ledger for human review, and JSON when another workflow needs the same inputs and audit rows.

When the page reports an input issue, fix that field before copying the YAML. The generated config text may still be visible, but the readiness state is the safer gate.

Interpreting Results:

Collector config ready means the entered values pass the generator checks and the YAML includes the required component sections. It does not confirm that a Collector image includes every referenced component, that the backend accepts the endpoint, or that the chosen bind address is safe in your network.

  • YAML readiness is the main copy gate. Fix blocking issues before using the generated config.
  • Signal coverage tells you which of traces, metrics, and logs will have service pipelines.
  • Processor order should show memory_limiter first for production-like traffic.
  • Memory limiter deserves review when it is omitted or sized without regard to container or host memory.
  • Remote exporter buffering warns when a remote exporter has no sending queue.
  • Debug exporter should be treated carefully when verbosity is high because payload content may appear in Collector output.

The false sense of safety to avoid is treating generated YAML as a live compatibility test. The follow-up check is external to the page: validate with the target Collector distribution, confirm the selected components support the selected signals, and send a small payload through the exact endpoint and exporter path.

Worked Examples:

Edge agent forwarding all signals

An edge Collector uses Edge agent to OTLP gateway, leaves traces, metrics, and logs enabled, accepts both OTLP transports on localhost, and exports to otel-gateway.example.com:4317 with verified TLS. The summary should show 3 pipelines, grpc+http, otlp, and memory first. Pipeline Ledger should list the same processor sequence for every signal.

HTTP gateway with a remote vendor endpoint

A gateway starts from Gateway to OTLP HTTP backend, binds the receiver to 0.0.0.0, and sends to https://otlp.vendor.example.com with an Authorization header value such as Bearer ${env:OTEL_EXPORTER_OTLP_TOKEN}. The audit should warn about receiver exposure while keeping remote exporter buffering ready when sending queue and retry are enabled.

Local debug Collector for a smoke test

A developer chooses Local debug collector, keeps the bind address at localhost, uses the debug exporter, and enables pprof plus zpages. The YAML should omit a remote exporter endpoint and include the debug verbosity setting. This is useful for local payload inspection, but it is not a production export path.

Troubleshooting a bad endpoint entry

If OTLP gRPC exporter is selected and the endpoint is entered as https://otel-gateway.example.com, the error list reports that the gRPC endpoint should be host:port without a URL scheme. Changing it to otel-gateway.example.com:4317 clears that blocking issue. For OTLP HTTP exporter, the opposite applies: the endpoint should start with http:// or https://.

FAQ:

Does this validate against my Collector distribution?

No. It checks form values and generates YAML from the selected components. Use otelcol validate --config collector.yaml with the same Collector distribution that will run the config.

Why is my gRPC endpoint rejected when it has HTTPS?

The OTLP gRPC exporter field expects a host:port value such as otel-gateway.example.com:4317. Use the OTLP HTTP exporter when the backend gives you an HTTP or HTTPS base URL.

When should I turn off the memory guard?

Use Omit memory_limiter only for small local tests or when another rollout control deliberately handles memory risk. For production-like traffic, keep the memory limiter first and coordinate the limit with host or container memory.

What happens if I enable no signals?

The readiness state fails and the error list asks you to enable at least one of traces, metrics, or logs. A Collector service section needs at least one signal pipeline to carry telemetry.

Do resource attributes replace existing service identity?

The generated resource processor uses upsert actions, so a common attribute can overwrite an existing value with the same key. Review shared attributes such as environment and namespace before applying them to every signal.

Does the page contact my Collector or backend?

No. It generates YAML, ledger rows, audit rows, and JSON from values entered on the page. It does not connect to a Collector, send telemetry, or test backend credentials.

Glossary:

Collector
The OpenTelemetry process that receives, processes, and exports telemetry data.
OTLP
OpenTelemetry Protocol, the telemetry transport used here over gRPC, HTTP, or both.
Receiver
A Collector component that accepts telemetry from SDKs, agents, or other senders.
Processor
A Collector component that handles telemetry between receiving and exporting.
Exporter
A Collector component that sends telemetry to a backend or debug output.
Memory limiter
A processor that checks Collector memory usage and can refuse data when configured limits are crossed.
Batch processor
A processor that groups spans, metric points, or log records before export.
Service pipeline
The service entry that activates receivers, processors, and exporters for traces, metrics, or logs.

References: