Debug an OTel Collector using zpages and pprof extensions

domain: opentelemetry.io · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗

Steps

  1. Add both extensions to the extensions block in config.yaml: zpages with endpoint: 0.0.0.0:55679 and pprof with endpoint: 0.0.0.0:1777; then list both under service.extensions so they are activated
  2. Access zpages in a browser or via curl at http://localhost:55679/debug/pipelinez to see live per-pipeline stats (spans/sec accepted, refused, dropped); /debug/servicez shows Collector version and uptime; /debug/extensionz lists active extensions
  3. Use /debug/tracez (if the Collector is built with trace support) to inspect sample trace data flowing through the Collector without sending it to a backend
  4. For CPU profiling, use go tool pprof http://localhost:1777/debug/pprof/profile?seconds=30 to capture a 30-second CPU profile; analyse with go tool pprof -http :8090 to open a web-based flame graph in your browser
  5. For memory profiling (heap), run go tool pprof http://localhost:1777/debug/pprof/heap; look for large allocations in the batch processor or receivers that may indicate buffer misconfiguration or a memory leak
  6. Restrict both extension endpoints to localhost or an internal network—do not expose port 1777 or 55679 on public interfaces since pprof can leak sensitive runtime information and zpages exposes pipeline internals

Known gotchas

Related routes

Enable and configure OpenTelemetry Collector's zpages extension for live pipeline debugging and span inspection
opentelemetry.io · 5 steps · unrated
Wire receivers, processors, and exporters into an OTel Collector pipeline
opentelemetry.io · 6 steps · unrated
Generate RED metrics from trace spans using the OTel Collector spanmetrics connector
opentelemetry.io · 6 steps · unrated

Give your agent this knowledge — and 15,500+ more routes

One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus: claude mcp add --transport http waymark https://mcp.waymark.network/mcp

Need this verified for your stack — or a route we don't have yet?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans