o11y-dev/opentelemetry-skill
Expert OpenTelemetry guidance for collector configuration, pipeline design, and production telemetry instrumentation. Use when configuring collectors, designing pipelines, instrumenting applications, implementing sampling, managing cardinality, securing telemetry, writing OTTL transformations, or setting up AI coding agent observability (Claude Code, Codex, Gemini CLI, GitHub Copilot).
94
94%
Does it follow best practices?
Impact
97%
6.92xAverage score across 4 eval scenarios
Passed
No known issues
validation.mdreferences/
OpenTelemetry Validation and Error Recovery
Use this reference when users ask to validate collector configs, verify live pipelines, or recover from runtime failures.
Validate before deploying
# Syntax and structural validation (local binary)
otelcol validate --config config.yaml
# Container-based dry-run (no outbound traffic)
docker run --rm -v $(pwd)/config.yaml:/etc/otelcol/config.yaml \
otel/opentelemetry-collector-contrib:latest \
validate --config /etc/otelcol/config.yamlVerify a live pipeline
# Health endpoint — returns 200 when collector is ready
curl -sf http://localhost:13133/ && echo "healthy"
# Tail logs for pipeline errors and dropped data
kubectl logs -l app=otelcol -f | grep -E "error|dropped|refused|timeout"
# Collector self-metrics (Prometheus scrape)
curl -s http://localhost:8888/metrics | grep -E "otelcol_processor_dropped|otelcol_exporter_send_failed"Error recovery guidance
| Symptom | Likely cause | Fix |
|---|---|---|
| Collector exits at start | Config parse error | Run otelcol validate; check indentation and quoted strings |
memory_limiter: data dropped in logs | Memory limit hit | Increase limit_percentage, reduce send_batch_size, or add upstream sampling |
exporter queue is full | Backend unreachable or slow | Verify endpoint reachability; increase queue_size; check retry_on_failure settings |
pipeline drops data on restart | No persistent queue | Add file_storage extension and set storage: file_storage/queue in exporter sending_queue |
| OTTL statement silently skipped | Type mismatch or nil value | Add error_mode: ignore; guard with where attributes["key"] != nil; use Int() / String() converters |
| Tail sampling misses spans | Spans split across collector instances | Use loadbalancing exporter with routing_key: traceID upstream |
docs
evals
cardinality-protection
claude-code-telemetry
collector-memory-limiter
scenario-1
scenario-2
scenario-3
scenario-4
tail-sampling-setup
references