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 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:

  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)