/dt-setup-genai

name: dt-setup-genai
description: >-
  Framework-independent decision process for instrumenting a GenAI/LLM app (Python or
  TypeScript, any provider/agent SDK) so it emits OTel GenAI semantic-convention
  (gen_ai.*) spans queryable in Dynatrace. Four steps: detect, instrument, enrich,
  validate. Decides which approach a given SDK needs; does not replace the concrete
  per-framework recipes in dynatrace-oss/dynatrace-ai-agent-instrumentation-examples.
  Trigger: "instrument this GenAI app", "add tracing to this LLM app", "how do I get
  gen_ai spans into Dynatrace", "onboard this agent app to AI Observability". Do NOT
  use for analyzing telemetry from an already-instrumented app (use dt-obs-genai) or
  for languages other than Python/TypeScript.
license: Apache-2.0

Instrument a GenAI app for Dynatrace

This is the shared decision process behind the per-framework recipes in [`dynatrace-oss/dynatrace-ai-agent-instrumentation-examples`](https://github.com/dynatrace-oss/dynatrace-ai-agent-instrumentation-examples) — referred to throughout as **the examples repo** — factored out so it applies to an SDK that repo doesn't cover yet. It tells you which recipe shape to reach for and why, and what "done" looks like regardless of the SDK/language. Once spans are flowing, load **dt-obs-genai** to analyze them.

When you should not use this skill

• Already instrumented, and you want to query/debug GenAI telemetry → **dt-obs-genai**.
• You already know the SDK's recipe and just want the copy-paste code → go straight to the examples repo; this skill decides *which* recipe shape applies, not replaces it.
• The app isn't Python or TypeScript → out of scope for this skill.

Where this skill must stop and ask

• **Any edit to the customer's application code** — show the diff, get a yes, first.
• **Credentials** — the customer creates the Dynatrace token and provider keys. Never print, log, or store a token value; reference it only via env var or secret store.
• **Deploying an OpenPipeline pipeline** to their tenant.
• **Provider config this skill can't infer** — Azure deployment name/API version, Ollama model tag, Bedrock region/profile.
• **Adding a collector to their runtime** — out of scope; infrastructure, not configuration.
• **Enabling message-content capture** — **off by default; only enable it if the user asks.**

Prompts/completions can carry PII or sensitive data, and the knob is **SDK-specific**: `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` for some instrumentors; a framework-native flag the env var does **not** control and that can **default to on** for others (e.g. pydantic-ai's `InstrumentationSettings(include_content=...)`); OpenInference captures content by default; and Traceloop/OpenLLMetry `opentelemetry-instrumentation-<sdk>` packages read `TRACELOOP_TRACE_CONTENT`, default **ON**, ignoring the OTel-standard var. Check the SDK's actual toggle so you don't ship capture on unnoticed; agree on redaction if needed.

The four steps

detect ─▶ instrument ─▶ enrich ─▶ validate
  │                                  │
  └──────────── feedback loop ───────┘
   (validate failure → fix in enrich or instrument)

1. Detect

Figure out *what* you're instrumenting before touching any code.

**Inputs:**

• Dependency manifest (`pyproject.toml` / `requirements.txt` / `package.json`) — which

LLM SDK(s), agent framework, or observability SDK are present (OpenAI, Anthropic, Bedrock, LangChain/LangGraph, CrewAI, MCP server/client, Langfuse, ...). An app can depend on more than one — see [references/multi-sdk-apps.md](references/multi-sdk-apps.md).

• Whether the host already runs Dynatrace **OneAgent** (`oneagent` process/package

present) — if so, OneAgent auto-instruments common HTTP/SDK calls with zero code changes, which changes everything downstream.

• Whether the app already has *any* OTel wiring — an existing global `TracerProvider`,

an existing `Traceloop.init()`/instrumentor call, or existing custom span code.

**Outputs:** a **routing key** `(framework/SDK, existing-instrumentation-state)` per SDK (see [references/multi-sdk-apps.md](references/multi-sdk-apps.md) if more than one), a **branch decision** (below), and a **native-OTel yes/no** decision (step 2) per SDK.

**How to decide native-OTel vs. fallback:** **prefer** SDKs with a pure-OTel path (native `gen_ai.*`). An SDK without one falls back to OpenInference — which closes the loop only if it emits `gen_ai.*` (Python semconv dual-write, step 2), else it stops at a normalizer gate. Work through these in order and stop at the first hit: 1. Check `references/examples-index.md` for the SDK. A listed `opentelemetry/` recipe is the fast path — use it. 2. If the SDK isn't listed, check the [OpenTelemetry registry](https://opentelemetry.io/ecosystem/registry/) and the vendor SDK's own docs for native OTel/`gen_ai.*` support (e.g. an `otel` extra, a `span_exporter`/tracer-provider hook, or built-in semconv attributes). Finding one → instrument it (step 2). 3. **No native OTel path → OpenInference.** Instrument with the matching `openinference-instrumentation-<sdk>` package from an examples-repo recipe; if not even that exists, hand-write manual `gen_ai.*` spans ([references/no-native-instrumentation.md](references/no-native-instrumentation.md)). OpenInference closes the loop **only when it emits `gen_ai.*`** — a Python instrumentor with semconv dual-write on (step 2). Otherwise (TS/node, older version, unset) spans stay `llm.*`/`openinference.*` and the skill **stops at a normalizer gate** ([references/enrich-normalization.md](references/enrich-normalization.md)), then resumes.

2. Instrument

Wire up span emission. **Prefer the pure-OTel path**; fall back to OpenInference only when no native OTel path exists. That fallback closes the loop only when it emits `gen_ai.*` (semconv dual-write, below); otherwise it stops at a normalizer gate before Vali