OpenTelemetry - Quick Reference

Full Reference: See advanced.md for context propagation, detailed metrics API, Collector configuration, Docker Compose stack, sampling strategies, and semantic conventions.

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: opentelemetry for comprehensive documentation.

Concepts

┌─────────────────────────────────────────────────────────────┐ │ OpenTelemetry │ ├─────────────────┬─────────────────┬─────────────────────────┤ │ Traces │ Metrics │ Logs │ │ (Distributed) │ (Aggregated) │ (Structured) │ ├─────────────────┴─────────────────┴─────────────────────────┤ │ OTLP Protocol │ ├─────────────────────────────────────────────────────────────┤ │ Collector (optional) │ ├─────────────────────────────────────────────────────────────┤ │ Jaeger │ Zipkin │ Prometheus │ Grafana │ DataDog │ etc. │ └─────────────────────────────────────────────────────────────┘

Node.js Setup

npm install @opentelemetry/sdk-node
@opentelemetry/auto-instrumentations-node
@opentelemetry/exporter-trace-otlp-http

Basic Configuration

// tracing.ts - Load FIRST before any other imports import { NodeSDK } from '@opentelemetry/sdk-node'; import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'; import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'; import { Resource } from '@opentelemetry/resources'; import { SEMRESATTRS_SERVICE_NAME } from '@opentelemetry/semantic-conventions';

const sdk = new NodeSDK({ resource: new Resource({ [SEMRESATTRS_SERVICE_NAME]: 'my-service', }), traceExporter: new OTLPTraceExporter({ url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces', }), instrumentations: [getNodeAutoInstrumentations()], });

sdk.start();

process.on('SIGTERM', () => { sdk.shutdown().finally(() => process.exit(0)); });

Application Entry Point

// index.ts import './tracing'; // MUST be first import import express from 'express';

const app = express();

Manual Traces

import { trace, SpanStatusCode } from '@opentelemetry/api';

const tracer = trace.getTracer('my-service', '1.0.0');

async function processOrder(orderId: string) { return tracer.startActiveSpan('process-order', async (span) => { try { span.setAttribute('order.id', orderId); await processOrderLogic(orderId); span.setStatus({ code: SpanStatusCode.OK }); } catch (error) { span.setStatus({ code: SpanStatusCode.ERROR, message: error.message }); span.recordException(error); throw error; } finally { span.end(); } }); }

Spring Boot Setup

<dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-tracing-bridge-otel</artifactId> </dependency> <dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-exporter-otlp</artifactId> </dependency>

management: tracing: sampling: probability: 1.0 otlp: tracing: endpoint: http://localhost:4318/v1/traces

Environment Variables

OTEL_SERVICE_NAME=my-service OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 OTEL_TRACES_SAMPLER=parentbased_traceidratio OTEL_TRACES_SAMPLER_ARG=0.1 # 10% sampling

When NOT to Use This Skill

• Simple application logging: Use logging frameworks instead

• Monolithic applications: May be overkill

• Vendor-specific APM: DataDog, New Relic have their own SDKs

• Development/debugging only: Standard logging may suffice

• Legacy systems: Migration effort may be high

Anti-Patterns

Anti-Pattern Why It's Bad Solution

Creating spans for every function Massive overhead Span only meaningful operations

100% sampling in production Performance impact, cost Use 1-10% sampling

Not propagating context Breaks distributed traces Inject/extract at service boundaries

Logging PII in span attributes Security/compliance violation Filter sensitive data

Forgetting to end spans Memory leak Always end spans in finally block

Synchronous exporters Blocks application Use batch processors

Quick Troubleshooting

Issue Cause Solution

Traces not appearing Exporter not configured Check OTEL_EXPORTER_OTLP_ENDPOINT

High memory usage Too many spans Enable sampling

Missing context propagation Not injecting headers Use propagation API

Performance degradation High sampling rate Reduce to 1-10%

SDK initialization error Import order wrong Initialize SDK before other imports

Monitoring Metrics

Metric Target

Trace latency (p99) < 10ms overhead

Span drop rate < 1%

Collector memory < 1GB

Export success rate

99%

Checklist

• SDK initialized before other imports

• Resource attributes configured

• Context propagation implemented

• Sampling strategy defined

• Graceful shutdown configured

• Collector deployed

• Dashboards created (Grafana)

• Alerts configured

Reference

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: opentelemetry for comprehensive documentation

• OpenTelemetry Docs