Debugging Collector Pipelines: OTCA practice questions

When telemetry goes missing somewhere between an application and a backend, the useful question is where along the path it stopped. The Collector gives you several tools for answering that question at each hop, and they work best in a fixed order: check the configuration, confirm data is arriving, watch it leave, then look deeper only if needed.

Configuration problems come first because they are cheap to rule out. The command otelcol validate with a --config flag checks a file without running pipelines, which makes it a good CI step. The otelcol components sub-command prints every receiver, processor, exporter, connector and extension compiled into the binary you are running, with a stability level per signal, so you can confirm that a vendor or custom build really contains the component you configured. A frequent mistake caught here is a receiver that is defined in the receivers section but never listed in any pipeline, which means it never starts receiving.

To see the data itself, add the debug exporter to a pipeline. With no settings it uses basic verbosity and logs one summary line per batch with record counts. Setting verbosity to normal prints roughly one line per record, and detailed prints every attribute, resource and scope field, including schema URLs. Because it writes through the Collector logger, its output appears wherever the Collector logs go, which is stderr by default.

The Collector's own logs are configured under service::telemetry::logs. The level field defaults to INFO and also accepts DEBUG, WARN and ERROR; encoding can be console or json. Raising the log level is different from raising debug exporter verbosity: one describes what Collector components are doing, the other prints the telemetry passing through.

Internal metrics tell you how far data got. Comparing counters such as otelcol_receiver_accepted_spans, otelcol_processor_incoming_items and otelcol_exporter_sent_spans hop by hop shows whether loss happens at ingestion, inside processing or at export. Refused counts at the receiver, enqueue failures at the exporter and send failures each point to a different stage. The verbosity of these metrics is set with service::telemetry::metrics::level, where normal is the default and none, basic and detailed are the alternatives.

Extensions cover live inspection. The health_check extension answers on localhost:13133 at path / and suits Kubernetes liveness and readiness probes. The zPages extension adds pages such as servicez, pipelinez, extensionz, featurez and tracez for in-process diagnostics without a backend. The pprof extension exposes Go profiling for performance investigations, which most users rarely need.

For multi-hop pipelines, the troubleshooting checklist asks the same things at every hop: are there errors in the logs, how is data ingested, how is it modified, how is it exported, what format is it in, how is the next hop configured, and is any network policy in the way.