How to test OpenTelemetry Collector pipelines with the debug exporter

Testing an OpenTelemetry Collector pipeline with the debug exporter shows whether telemetry reaches the pipeline before a backend is involved. The exporter writes received records to the Collector log, so a local smoke test can confirm the receiver and processor path without waiting for backend credentials, routing, or indexing.

A local OTLP HTTP receiver on 127.0.0.1:4318 feeds a traces pipeline for the smoke test. The same pattern works for metrics or logs when the endpoint, payload, and pipeline signal match the telemetry type being tested.

Use verbosity: detailed only while proving the pipeline. Detailed debug output can include service names, routes, attributes, and other telemetry fields, so remove the exporter or switch the pipeline to the intended backend after the smoke test passes.

1. Create a temporary Collector configuration for the smoke test.

   collector-debug.yaml

   receivers:
     otlp:
       protocols:
         http:
           endpoint: 127.0.0.1:4318
   
   exporters:
     debug:
       verbosity: detailed
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         exporters: [debug]

   A configured receiver or exporter is active only after a service pipeline references it. Add the processors under test between receivers and exporters when the smoke test needs to prove an existing processor chain.
   Tool: OpenTelemetry Collector Config Generator

2. Validate the Collector configuration.

   $ otelcol validate --config=collector-debug.yaml

   No output with a zero exit status means the configuration parsed successfully and every referenced component exists in the Collector build.

3. Start the Collector in the foreground.

   $ otelcol --config=collector-debug.yaml
   2026-06-18T06:30:19.005Z info Starting HTTP server {"otelcol.component.id":"otlp","otelcol.component.kind":"receiver","endpoint":"127.0.0.1:4318"}
   2026-06-18T06:30:19.005Z info Everything is ready. Begin running and processing data.

   Leave this terminal open while sending the smoke payload from another terminal.

4. Create an OTLP HTTP trace payload.

   trace.json

   {
     "resourceSpans": [
       {
         "resource": {
           "attributes": [
             {
               "key": "service.name",
               "value": {
                 "stringValue": "checkout-api"
               }
             }
           ]
         },
         "scopeSpans": [
           {
             "scope": {
               "name": "manual-smoke"
             },
             "spans": [
               {
                 "traceId": "5b8efff798038103d269b633813fc60c",
                 "spanId": "eee19b7ec3c1b174",
                 "name": "debug-exporter-smoke",
                 "kind": 1,
                 "startTimeUnixNano": "1717260000000000000",
                 "endTimeUnixNano": "1717260001000000000",
                 "attributes": [
                   {
                     "key": "http.route",
                     "value": {
                       "stringValue": "/checkout"
                     }
                   }
                 ]
               }
             ]
           }
         ]
       }
     ]
   }

5. Send the trace payload to the local OTLP HTTP receiver.

   $ curl --silent --show-error --include --request POST http://127.0.0.1:4318/v1/traces \
     --header 'Content-Type: application/json' \
     --data @trace.json
   HTTP/1.1 200 OK
   Content-Type: application/json
   Content-Length: 21
   
   {"partialSuccess":{}}

   The 200 OK response confirms that the receiver accepted the payload. Use /v1/metrics or /v1/logs with a matching payload when testing a metrics or logs pipeline.

6. Inspect the Collector terminal for debug exporter output.

   2026-06-18T06:30:25.034Z info Traces {"otelcol.component.id":"debug","otelcol.component.kind":"exporter","otelcol.signal":"traces","resource spans":1,"spans":1}
   2026-06-18T06:30:25.034Z info ResourceSpans #0
   Resource attributes:
        -> service.name: Str(checkout-api)
   ScopeSpans #0
   InstrumentationScope manual-smoke
   Span #0
       Trace ID       : 5b8efff798038103d269b633813fc60c
       ID             : eee19b7ec3c1b174
       Name           : debug-exporter-smoke
       Kind           : Internal
   Attributes:
        -> http.route: Str(/checkout)

   The otelcol.signal value, service.name resource attribute, span name, trace ID, and payload attribute prove that the test record passed through the traces pipeline.

7. Stop the foreground Collector with Ctrl+C after the smoke test.

   Do not leave verbosity: detailed on normal production traffic. The debug exporter can write request paths, service names, resource attributes, and other telemetry fields to Collector logs.

   Related: How to export telemetry from the OpenTelemetry Collector with OTLP