phoenix-integration-snippets

# 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:** `app/src/components/project/integrationSnippets/` — read existing files to match conventions.

Do NOT pass `endpoint`/`url` in snippet code — the onboarding UI displays env vars (including `PHOENIX_COLLECTOR_ENDPOINT`) separately, and both `register` functions read it automatically.

**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:** `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)