OpenTelemetry: traces, metrics, logs — Migration Playbook — Practical Guide (Apr 28, 2026)

OpenTelemetry: traces, metrics, logs — Migration Playbook

body { font-family: Arial, sans-serif; line-height: 1.6; max-width: 900px; margin: 2rem auto; padding: 0 1rem; }
h2, h3 { colour: #005a9c; }
pre { background: #f4f4f4; padding: 1rem; overflow-x: auto; border-left: 4px solid #005a9c; }
code { font-family: Consolas, monospace; }
p.audience, p.social { font-style: italic; colour: #555; }
ul { margin-top: 0; }

OpenTelemetry: traces, metrics, logs — Migration Playbook

Level: Intermediate

As of April 28, 2026 – applicable for OpenTelemetry stable versions 1.18 and later.

Introduction

OpenTelemetry (OTel) has emerged as the de facto standard for observability, unifying traces, metrics, and logs under a single, vendor-neutral API and SDK. Organisations migrating existing instrumentation to OpenTelemetry reap the benefits of portability, comprehensive observability, and improved diagnostic capabilities. This playbook provides a practical, step-by-step guide for intermediate engineers already familiar with basic observability and distributed tracing concepts.

Prerequisites

OpenTelemetry SDK/API internal knowledge: Familiarity with core concepts like TracerProvider, MeterProvider, Span, and exporters specific to your language.
Instrumentation landscape: Understand current tracing and metrics tools in use (e.g., Jaeger, Prometheus clients, Fluentd logs) and whether custom instrumentation exists.
Target environment: Knowledge of your application runtime platform (e.g., JVM, Node.js, Go) — OpenTelemetry libraries differ slightly in features and setup.
Compatibility check: Confirm versions of OpenTelemetry libraries support required signal types and exporters (stable since ~v1.15).
Backend readiness: Ensure your observability backend supports OpenTelemetry Protocol (OTLP) or has compatible receivers for traces, metrics, and logs.

Hands-on Steps

Step 1: Select Your OpenTelemetry Components

Choose language-specific OpenTelemetry libraries for Tracing, Metrics, and Logging. Most languages support the @opentelemetry/sdk-trace-*, @opentelemetry/sdk-metrics, and preview or stable logging APIs:

Tracing and metrics are stable across most languages since v1.15+
Logging remains experimental or preview in some SDKs; consider if you want to ingest logs via OpenTelemetry or continue with your existing solution.

When to choose OpenTelemetry logging vs existing logging tools? Use OTel logs if you want unified, correlated signals (trace + metrics + logs). For mature logging ecosystems, continue as-is but forward data where possible.

Step 2: Install and Initialise SDKs

Install or upgrade to the latest stable OpenTelemetry SDK packages for your platform. Initialise the providers early in your app:

// Node.js example for tracing + metrics setup
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { MeterProvider, PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-http');

const tracerProvider = new NodeTracerProvider();
const traceExporter = new OTLPTraceExporter({ url: 'https://otel-collector.example.com/v1/traces' });
tracerProvider.addSpanProcessor(new SimpleSpanProcessor(traceExporter));
tracerProvider.register();

const meterProvider = new MeterProvider();
const metricExporter = new OTLPMetricExporter({ url: 'https://otel-collector.example.com/v1/metrics' });
meterProvider.addMetricReader(new PeriodicExportingMetricReader({ exporter: metricExporter }));

// Optionally capture logs once supported and stable by your SDK

Step 3: Migrate or Add Instrumentation

For custom instrumentation:

Replace existing tracing calls with tracer.startSpan() and ensure context propagation.
Convert custom metrics to use OpenTelemetry’s metrics API; prefer instruments like counters and histograms.
Capture logs via OpenTelemetry where supported, linking them to traces by context.

For auto-instrumentation:

Use OpenTelemetry’s automatic instrumentation libraries where available (e.g., @opentelemetry/instrumentation-http for Node.js).
Ensure instrumentation versions match the main SDK version polarity to avoid API conflicts.

Step 4: Configure Exporters and Collectors

Consider deploying or updating an OpenTelemetry Collector between your app and backend. Collector decouples your app from backend changes and allows protocol/frame transformation. Configure collectors for your use case:

OTLP receivers for traces, metrics, logs
Exporters to backend services like Jaeger, Prometheus, Elasticsearch

Example collector snippet for OTLP receiver with Jaeger exporter:

receivers:
  otlp:
    protocols:
      grpc:
      http:

exporters:
  jaeger:
    endpoint: "http://jaeger-collector:14268/api/traces"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [jaeger]

Step 5: Gradual Rollout and Parallel Runs

Run OpenTelemetry instrumentation alongside legacy tools during migration. Compare metrics and traces for discrepancies, adjust sampling rates, and exporter configurations.

Common Pitfalls

Version mismatches: Mixing incompatible versions of SDK and instrumentation packages often causes crashes or missing data.
Incomplete context propagation: Failing to propagate context across async boundaries breaks trace links.
Over-instrumentation: Capturing too many spans or metrics can lead to high overhead and backend overload.
Logs integration gaps: Logging support varies by language and may require different agents or SDK versions noted as preview features.
Ignoring exporter failures: Export errors rarely throw exceptions but cause silent data loss if not monitored.
Ignoring backend limits: Be aware of backend rate limits and sampling to avoid resource exhaustion and unexpected dropouts.

Validation

Confirm data flow and signal quality by:

Viewing traces in your backend with expected spans, timings, and attributes.
Checking metrics aggregation and dashboards for correctness and freshness.
Ensuring logs include trace and span IDs for correlation if using OpenTelemetry logging.
Using otel-cli or similar command-line tools for manual trace export validation.
Monitoring OTLP exporter logs and OpenTelemetry Collector metrics for dropped spans or errors.

Checklist / TL;DR

Understand your current observability setup and backends.
Select supported OpenTelemetry SDKs for traces, metrics; evaluate logging support.
Install, initialise SDKs and set up exporters for OTLP protocol.
Migrate custom instrumentation and/or enable auto-instrumentation.
Deploy or update OpenTelemetry Collector if required for protocol translation.
Run in parallel with legacy tools; validate trace/metric/log data end-to-end.
Address common pitfalls: context propagation, version mismatch, performance tuning.
Use backend dashboards and OTLP observability to verify signal health.