otel-migration

OpenTelemetry Migration for Existing Applications

Guide for retrofitting OpenTelemetry into an existing, uninstrumented application. This covers the phased migration approach, context propagation refactoring, logging and metrics bridges, and verification. This is distinct from greenfield OTel setup (see otel-instrumentation skill) and Beeline-specific migration (see beeline-migration skill).

When to Use This Skill

Use this skill when the user has an existing application that:

• Has no OpenTelemetry instrumentation and needs to add it
• Has existing logging, metrics, or context patterns that must coexist with OTel
• Needs to refactor function signatures to thread trace context through the call stack
• Uses a framework with OTel middleware gotchas (e.g., Fiber, Gin, Express)

For greenfield OTel setup, use the otel-instrumentation skill instead. For Beeline-to-OTel migration, use the beeline-migration skill instead. For understanding why to instrument, see the observability-fundamentals skill.

Migration Phases

The migration follows six phases in order. Each phase is independently deployable and verifiable. Context propagation (Phase 3) is typically ~60% of the effort.

Phase 1: SDK Initialization and Shutdown

Set up TracerProvider, MeterProvider, and LoggerProvider with OTLP exporters. Wire initialization early in the application's entry point and shutdown in signal handlers.

Key guidance:

• SDK init must happen before any application code that might create spans — one of the first things in your entry point, before config loading or storage initialization
• Shutdown ordering matters: flush traces, then metrics, then logs. Use a timeout (10-30s)
• If init fails, the application should still work — log the error and continue without telemetry
• For language-specific SDK setup, consult ${CLAUDE_PLUGIN_ROOT}/skills/otel-instrumentation/references/sdk-setup-by-language.md

Phase 2: HTTP Middleware (Auto-Instrumentation)

Add OTel middleware to your HTTP framework. This gives you automatic spans for every inbound request with zero code changes to handlers. This is the highest-ROI step.