Phoenix Integration Snippets

---
name: phoenix-integration-snippets
description: >
  Generates onboarding code snippets for Phoenix tracing integrations and wires
  them into the project onboarding UI. Produces install dependencies and
  implementation sections for SDKs like OpenAI, LangChain, Vercel AI SDK, and
  others. Supports Python and TypeScript. Use when asked to create onboarding
  code, tracing setup snippets, quickstart examples, or getting-started code
  for a framework integration.
license: Apache-2.0
metadata:
  author: oss@arize.com
  version: "2.0.1"
  languages: Python, TypeScript
  internal: true
---

# Phoenix Integration Snippets

Generate onboarding snippets (install + implementation) for Phoenix tracing integrations and add them to the project onboarding UI.

## Workflow

Copy this checklist and track progress:

```
- [ ] 1. Research: read integration docs and OpenInference repo
- [ ] 2. Determine language support (Python, TypeScript, or both)
- [ ] 3. Generate snippets following the format below
- [ ] 4. Test every language variant against Phoenix
- [ ] 5. Wire into the onboarding UI
- [ ] 6. Report results with links to trace pages
```

**Step 1: Research.** Read the relevant file in `docs/phoenix/integrations/` for the framework. Also check the OpenInference repo for example code: https://github.com/Arize-ai/openinference

**Step 4: Test.** See [Testing](#testing) below. Only proceed to wiring into the UI when traces are confirmed.

**Step 5: Wire into the onboarding UI.** After adding `docsHref` and `githubHref`, verify every URL returns HTTP 200 before committing. For GitHub links, prefer the OpenInference repo (`https://github.com/Arize-ai/openinference/tree/main/...`).

**Step 6: Report.** Provide clickable links to the Phoenix project pages (e.g., `http://localhost:6006/projects/<base64-id>/traces`).

## Snippet Format

Each snippet has two parts:

**Packages:** Array of package names. Order: phoenix-otel first, then instrumentation package, then SDK.

Do not assume the framework package bundles its model provider SDK. In a clean env, verify the exact imports used by the snippet; if the framework's OpenAI/Gemini/etc. adapter requires a separate SDK package, include it explicitly in `packages`.

**Implementation:** Working, copy-pasteable code that produces at least one trace. 10-20 lines, meaningful example prompt, no print/log statements.

## Adding to the Onboarding UI

### 1. Add implementation function

**Directory:** `js/app/src/components/project/integrationSnippets/` — read existing files to match conventions.

Whether a snippet passes an endpoint depends on what consumes it. Either way the value comes from `PHOENIX_COLLECTOR_ENDPOINT`, which the onboarding UI displays alongside the snippet.

- **`register()`-based snippets** — do NOT pass `endpoint`/`url`. Both `register` functions read `PHOENIX_COLLECTOR_ENDPOINT` and derive the OTLP target from it.
- **Verbatim exporters** — anything that POSTs to exactly the URL it is handed, such as `@mastra/arize`'s `ArizeExporter` or a bare `OTLPTraceExporter`, MUST receive the full OTLP URL explicitly, built from the same variable:

  ```typescript
  endpoint: `${process.env.PHOENIX_COLLECTOR_ENDPOINT ?? "http://localhost:6006"}/v1/traces`,
  ```

  These exporters do not read the environment and do not append the OTLP path. Omitting the endpoint or passing a bare base URL loses every span, with no error.

**Python:** Use `auto_instrument=True` — no manual instrumentor calls. SDK imports must come _after_ `register()`.

Exception: if the framework emits native OpenTelemetry spans and uses a mutating span processor, start with `register(...)` so Phoenix becomes the global provider the framework will use. Then add the mutating processor so it replaces Phoenix's default processor, and add the Phoenix exporter back after it.

**TypeScript:** ESM imports are hoisted so import ordering doesn't matter. `await provider.forceFlush()` is required in short-lived scripts.

### 2. Register the integration

**File:** `js/app/src/pages/project/integrationRegistry.tsx`

Import your function and add an entry to `ONBOARDING_INTEGRATIONS`. Pass snippet functions as direct references (they match the `getImplementationCode` type in `integrationDefinitions.ts`).

## Testing

Test snippets **as written** — the exact code the user will see in the onboarding UI. If any modification is required to make a snippet work, that is a bug.

### Isolated test environments

Create a **fresh environment per integration** with only the packages from that snippet's `packages` array. This prevents false positives from cross-contamination (e.g., an installed `openinference-instrumentation-openai` producing extra traces when testing a LangChain snippet).

Set `PHOENIX_COLLECTOR_ENDPOINT` and run the snippet code verbatim.

Use a **fresh Phoenix project name per test run**. Reusing an existing project can mask failures by making old traces look like the new snippet worked.

### Validation checklist

For each snippet, verify:

- No export errors (no `405`, no `Failed to export span batch`)
- Traces appear in Phoenix under the expected project name
- Trace kind and structure match expectations (e.g., LangChain shows `chain` spans, not just bare `llm` spans)
- Only one top-level trace per invocation (multiple top-level traces suggest instrumentor cross-contamination)

### When a snippet doesn't work as-is

If you must modify the snippet code to get traces flowing, **do not silently work around it and continue**. Instead:

1. **Fix the snippet** if the change is small and clearly correct (e.g., a typo, missing import)
2. **Flag to the user** if the fix requires a design decision (e.g., the SDK doesn't support env-var-based config, or auto-instrumentation doesn't work for this framework)