/dt-setup-openinference-migration

name: dt-setup-openinference-migration
description: >-
  Migrate a GenAI/LLM app off Traceloop/OpenLLMetry onto OpenInference with its OTel gen_ai.*
  semconv option enabled (`enable_genai_semconv` / `OPENINFERENCE_ENABLE_GENAI_SEMCONV`). Covers
  detecting the existing Traceloop setup, swapping the instrumentor per SDK, and the
  ingestion-shape question that decides what's fixable afterward — an app-owned OTel trace
  exporter vs. instrumentation-only with OneAgent picking up the spans. Flags that the semconv
  option is additive, not a replacement — legacy llm.*/openinference.* attributes keep emitting
  alongside gen_ai.* — and covers the resulting cardinality trade-off and removal options
  (Collector transform vs. OpenPipeline), checking which is actually available first. Trigger:
  "migrate off Traceloop", "migrate off OpenLLMetry", "move to OpenInference", "enable
  OpenInference GenAI semconv". Do NOT use for a first instrumentation with no existing
  Traceloop setup, or an OpenInference app that never enables semconv (both dt-setup-genai).
license: Apache-2.0

Migrate off Traceloop/OpenLLMetry onto OpenInference

The migration-specific decision process for an app that's **already emitting spans via Traceloop/OpenLLMetry** and must move onto OpenInference with its `gen_ai.*` semantic-convention option on. It shares Detect/Validate machinery with **dt-setup-genai** — load that skill for the four-step instrument/enrich model, the `dtctl` validation contract, and multi-SDK handling. This skill covers only what differs: identifying the Traceloop setup, the instrumentor swap, and the gaps that remain once `gen_ai.*` flows — legacy attributes OpenInference keeps emitting, invocation parameters left unparsed, and guardrail signals the instrumentation never captured.

When you should not use this skill

• No existing Traceloop/OpenLLMetry instrumentation to migrate away from → **dt-setup-genai**

(greenfield or enhance-existing instrumentation from scratch).

• Already on OpenInference, semconv option never enabled, spans still arrive as

`llm.*`/`openinference.*` → load the **dt-setup-genai** skill and use its normalizer gate (`references/enrich-normalization.md`) instead — not a migration.

• TypeScript/Node app, or any language other than Python → out of scope. The semconv option

this skill's flow depends on exists only in the Python OpenInference SDK today — a TypeScript app moving off Traceloop still needs dt-setup-genai's normalizer gate afterward, not this skill.

Where this skill must stop and ask

• **Any edit to the customer's application code** — show the diff, get a yes, first.
• **Whether to remove the legacy `llm.*`/`openinference.*` attributes** (step 4a) — a

trade-off, not a default to silently apply.

• **Deploying an OTel Collector transform or an OpenPipeline pipeline** to the tenant — same

boundary dt-setup-genai draws — or the `gen_ai_normalizer` (collector processor or OpenPipeline pipeline), only after Validate shows gaps it would close. OpenPipeline needs extra care: its routing configuration is a single object shared by every pipeline on the tenant — read [references/openpipeline-safety.md](references/openpipeline-safety.md) first.

• **Adding app code to capture a guardrail signal** the instrumentation doesn't emit (step 4c).
• **Credentials** — never print, log, or store a token value.
• **Message-content capture** — OpenInference captures prompt/response content by default,

independent of the semconv flag (as Traceloop does via `TRACELOOP_TRACE_CONTENT`); confirm the user still wants it once instrumentation changes hands.

The migration flow

baseline ─▶ detect Traceloop ─▶ ingestion shape ─▶ swap instrumentor ─▶ close semconv gaps ─▶ validate

0. Capture baseline and rollback state

Before editing anything, record what the service emits today and how to undo the change — the swap renames attributes and drops metrics that dashboards or alerts may read. Baseline query, consumer inventory, rollback checklist: [references/baseline-and-rollback.md](references/baseline-and-rollback.md).

1. Detect the existing Traceloop/OpenLLMetry setup

Confirm this is actually a migration — grep patterns and the package-name trap (some Traceloop packages are named `opentelemetry-instrumentation-<sdk>`, like genuine OTel ones) are in [references/detect-traceloop.md](references/detect-traceloop.md). Record which SDK(s) it wraps — each needs its own `openinference-instrumentation-<sdk>` replacement in step 3.

2. Confirm the ingestion shape

This decides what's actually fixable in step 4, so settle it before touching code. Three situations, not interchangeable for the cardinality question:

• **App-owned trace exporter** — the app builds its own `TracerProvider`, attaches a

`BatchSpanProcessor` + OTLP exporter, and calls `set_tracer_provider(...)` before the instrumentor runs. The app controls the exporter, so a collector can sit in front of it.

• **Instrumentation-only, OneAgent picks it up** — the code calls only the instrumentor's

`.instrument(...)`, with no `TracerProvider`/exporter setup; on a OneAgent-monitored host, OneAgent captures the spans by injecting into the process. Nothing the app controls sits on the wire, so a collector transform isn't an option later — only OpenPipeline can touch these spans post-ingestion.

• **Traceloop-managed exporter** — the app calls `Traceloop.init()` and none of the symbols

above appear, but Traceloop itself creates the `TracerProvider` and a default OTLP exporter (destination via `TRACELOOP_BASE_URL`/`TRACELOOP_HEADERS`/`TRACELOOP_API_KEY`). Replacing it with only an OpenInference instrumentor silently drops the export path — first add an explicit provider + exporter with the same destination, then remove the init. `init_instrumentations(...)` is different: instrumentation only, like the second shape.

Full detection heuristic and a worked example of each shap