migrate-from-openinference

Migrate an OpenInference instrumentation-* package

Migrate an openinference-instrumentation-<source> package from https://github.com/open-telemetry/donation-openinference into this repo. The result emits OTel GenAI semantic conventions through opentelemetry-util-genai.

Two modes, decided by the "Before you start" gate below:

• Greenfield migration — no package for the library exists yet. Create a new implementation under instrumentation/. The default, and what the bulk of this skill describes.
• Augment an existing package — the repo already ships opentelemetry-instrumentation-genai-<lib>. Don't re-create it; inventory what it covers, diff against OpenInference, and add only the missing parts. See Augment mode.

For a greenfield migration the major work items are: rewriting the patcher to method-level (step 5), mapping every request/response shape into OTel InputMessage/OutputMessage parts (step 6), and migrating the unit-test corpus while filtering openinference-framework plumbing tests out (step 7).

Inputs

User specifies the source, e.g. openinference-instrumentation-crewai.

• Source: It should point to one of the folders in https://github.com/open-telemetry/donation-openinference/tree/main/python/instrumentation/. Fetch a fresh shallow clone if you don't already have one locally:

  git clone --depth=1 https://github.com/open-telemetry/donation-openinference.git /tmp/openinference
  

  and use /tmp/openinference/python/instrumentation/<source>/ as the source path in step 1.

User may also provide the target package name. If not provided: derive it from the source name:

• drop the leading openinference-instrumentation-. Remaining part should match the instrumented library name as it appears on PyPI. If it's not the case, flag it.
• The target package name should be opentelemetry-instrumentation-genai-<lib> where <lib> is the instrumented library name (e.g. openai, anthropic, bedrock). For example:
  • openinference-instrumentation-openai → opentelemetry-instrumentation-genai-openai
  • openinference-instrumentation-anthropic → opentelemetry-instrumentation-genai-anthropic Confirm the chosen name with the user.

Before you start: is there already a package for this library?

Once the target name is settled, check whether the repo already ships it:

ls instrumentation/opentelemetry-instrumentation-genai-<lib> 2>/dev/null

• Exists → augment mode: don't scaffold a new package. OpenInference is now a second reference to mine for coverage the existing package lacks. Jump to Augment mode.
• Doesn't exist → greenfield migration; continue below.

If a near-name sibling (a -agents / -client suffix) might instrument a different surface of the same vendor, confirm the target name with the user before deciding.

Before you start: check for native OTel instrumentation

AI SDKs increasingly ship their own OpenTelemetry GenAI instrumentation. When they do, migrating the OpenInference package is redundant. So before writing any code, determine whether the instrumented library is self-instrumenting.

# 1. Does the SDK depend on the OTel API / semconv?
pip show <lib> | grep -i requires        # or read its pyproject / METADATA
#    a dependency on opentelemetry-api or opentelemetry-semantic-conventions
#    is the tell.
# 2. Does its source actually emit GenAI spans?
python -c "import <lib>, os; print(os.path.dirname(<lib>.__file__))"
rg -l "opentelemetry|semconv\._incubating\.attributes\.gen_ai" <site-packages>/<lib>

A dependency on opentelemetry-api (or -semantic-conventions) plus gen_ai_attributes usage in the SDK source means the library is self-instrumented. Confirm empirically: set a global TracerProvider (native hooks often activate only when a real, non-proxy provider is configured), make one call, and inspect the emitted spans' instrumentation scope.

If the library is self-instrumented, do NOT migrate the OpenInference package. Pivot the work:

1. Ignore the OpenInference instrumentation entirely — the vendor owns the spans; there is nothing to re-implement, and no src/ instrumentor / patcher to write.
2. Write conformance tests against the native instrumentation. Follow step 8 / the write-conformance-tests skill, but each scenario's run() configures providers and enables the native tracer (e.g. sets a global TracerProvider) instead of calling a *Instrumentor — then runs the emitted telemetry through weaver live-check.
3. Identify gaps / inconsistencies between the native output and the GenAI semconv: missing operations, wrong operation name, legacy/duplicate attributes, no metrics, no content-capture controls, no util-genai content modes / completion-hook / upload support, etc. Record each as an expected_violation or a documented skip, same as a normal migration.
4. Write MIGRATION_REPORT.md stating the library is self-instrumented, the conformance results, and the gap list — that report is the deliverable. Stop and surface the finding to the user. Do not build a competing package unless they explicitly decide to (e.g. to suppress native instrumentation and layer util-genai features on top).

Only when the library has no native OTel instrumentation do you continue with the migration flow below.

Reference material

• OTel GenAI spans: https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai — authoritative attribute names, spans, logs, and metrics definitions.

• OpenInference → OTel attribute mapping (Arize-maintained): https://github.com/Arize-ai/openinference/blob/e9a8746daeb184c9aabc68ca29c05909ddcccf1e/spec/genai/README.md. Use as a quick lookup for what an OpenInference attribute roughly corresponds to in OTel; when the mapping disagrees with the official semconv, the official semconv wins.

• Message JSON schemas:

  • input messages: https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/gen-ai-input-messages.json
  • output messages: https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/gen-ai-output-messages.json
  • system instructions: https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/gen-ai-system-instructions.json
  • tool definitions: https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/gen-ai-tool-definitions.json
  • retrieval documents: https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/gen-ai-retrieval-documents.json

• Code for above models: https://github.com/open-telemetry/semantic-conventions-genai/tree/main/docs/gen-ai/non-normative/models.py.

Non-negotiable rules

The repo-wide rules in AGENTS.md already apply (telemetry through opentelemetry-util-genai public surface only, no type: ignore, semconv enums over string literals, re-raise caught exceptions). The rules below are the ones the migration is most likely to violate:

1. Zero OpenInference dependencies. No openinference-instrumentation, no openinference-semantic-conventions, no openinference-* anywhere in the migrated package's src/ or tests/. Verify with rg openinference instrumentation/<target> — output must be empty.

2. Public util-genai surface only. Beyond the AGENTS.md rule, the migrated package must not import any opentelemetry.util.genai._* module — the allowed modules are enumerated in step 4.

3. Ignore all other OpenInference instrumentations during the migration. The only instrumentation code to read is the OpenInference package being migrated plus opentelemetry-util-genai. Build from first principles: original OpenInference code + util-genai public API + official semconv spec.

4. Never work around gaps. If util-genai or the GenAI semconv is missing something, flag it and fail the test intentionally

5. Do not make OTel API calls. Exception: semconv attributes that exist in the registry but have no named property on InferenceInvocation (e.g. gen_ai.usage.cache_creation.input_tokens, gen_ai.usage.cache_read.input_tokens) may be set via invocation.attributes[KEY] = … — that's still going through the util-genai extension point. Import the key from opentelemetry.semconv._incubating.attributes.gen_ai_attributes. Do not invent attribute names that aren't in the semconv.

6. Reuse VCR cassettes. Reuse cassettes from the OpenInference tests when possible.

7. Conformance tests must never be silently skipped. When instrumentation can't be made conformant due to missing information, gap in semantic conventions, or in util-genai, still write the scenario and let it fail.

   Ask user to decide if they want to mark the scenario as skipped with a reason, or add an expected_violation in the scenario that covers the missing piece. All these must be documented in MIGRATION_REPORT.md as well, with links to the skipped scenario and the expected violation.

8. Do not modify weaver policies.

Augment mode: the package already exists

The package already has a working, conformant implementation; OpenInference is just another reference to mine for missing coverage. The job is a tight, delta-only PR that closes specific gaps — not a rewrite.

All Non-negotiable rules apply to every line you add, plus two specific to this mode:

• Don't rewrite or "improve" existing code. Leave the existing patcher, wrappers, and tests alone unless OpenInference reveals a concrete bug — and then it's a separate PR. No opportunistic refactors.
• Match the existing package's conventions. New wrappers,

Content truncated.