[IBJunior]

Why

Cameron inherited Langfuse tracing from the starter: a vendor callback pointed at a hosted backend by default. A trace carries every prompt, tool argument and transaction, so that setup quietly broke Cameron's third rule — financial data stays on infrastructure the owner controls. Tracing now uses OpenTelemetry's GenAI conventions and goes to a backend the owner runs.

What changed

• src/lib/tracing/
  • GenAiTracer is a LangChain callback, attached per request in agentService.ts. It emits:
    • invoke_agent for the run, chat for each model call and execute_tool for each tool call; graph nodes and middleware get no span;
    • an approval pause as a cameron.approval.requested event on the run span, with tool names only;
    • a resumed run's approve/reject counts.
  • semconv.ts is the only file naming gen_ai.* / cameron.* attributes, because the conventions are still at Development stability.
• Off by default, two opt-ins
  • Tracing turns on only when OTEL_EXPORTER_OTLP_ENDPOINT is set. The code has no default destination.
  • Content capture (OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true) is a separate switch. With it off, no prompt, message, tool argument or result, or error message leaves the process.
• src/instrumentation.ts starts the OTel Node SDK with the OTLP exporter.
  • The Node-only part is in src/instrumentation.node.ts, so the Edge build never sees it.
  • Both files have to live in src/. With an src/app layout, next build only looks there: a file at the repo root still runs under pnpm dev, but the production image leaves it out without any error. The Langfuse setup inherited from the starter had the same problem, so it never traced in Docker.
  • Next.js's own route and fetch spans stay in the same trace, so agent tracing and ordinary request tracing sit side by side.
• compose.yaml also passes OPENAI_COMPATIBLE_API_KEY to the production web service, and runs Phoenix as the default backend, split the same way as the data:
  • dev phoenix: --profile tracing, port 6006;
  • production phoenix-prod: --profile full, port 6016, its own volume;
  • both are bound to localhost only, with Phoenix's usage telemetry off;
  • production uses PROD_OTEL_* variables, so a dev value in .env can't redirect production traces.
• Removed @langfuse/*. Langfuse, Jaeger or any OTLP backend is now an endpoint change; see docs/OBSERVABILITY.md.
• Docs: docs/OBSERVABILITY.md is rewritten, the AGENTS.md "Two stacks" table lists Phoenix, and the Tracing section replaces the Langfuse one.

Verification

• pnpm test (379 tests, 22 of them new and offline, run against an in-memory exporter) and tsc --noEmit pass; pnpm build succeeds.
• Live on the dev stack, against the OpenAI-compatible provider:
  • a read, an approved write and a denied write all traced correctly, including the approval event and resume counts;
  • each thread is one Phoenix session;
  • with capture off, no content attributes appeared;
  • pointing the endpoint at Jaeger 2.11 delivered the same spans with no code change.
• Production stack (--profile full): agent runs trace to phoenix-prod on 6016, including messages when capture is on. The production Docker image needs fix(fonts): self-host Geist so the production build needs no network #50, which is already merged into this branch.

No evals: nothing the model reads changed.

🤖 Generated with Claude Code