Skip to content

docs(tracing): add Langfuse tracing guide and fix OTLP endpoint example - #1471

Open
Ethan-Xingyue wants to merge 2 commits into
oceanbase:masterfrom
Ethan-Xingyue:docs/trace-with-langfuse
Open

docs(tracing): add Langfuse tracing guide and fix OTLP endpoint example#1471
Ethan-Xingyue wants to merge 2 commits into
oceanbase:masterfrom
Ethan-Xingyue:docs/trace-with-langfuse

Conversation

@Ethan-Xingyue

Copy link
Copy Markdown
Collaborator

Which issue or RFC does this PR close?

No dedicated issue. This delivers the "Langfuse integration" item assigned in Discussion #1402 ("20260830 weekly",
observability and evaluation table) and in the 2026-08-16 meeting notes (docs/en/meetings/2026-08-16.md). It stays
within RFC 0046 (Observability Foundations): PowerContext keeps exporting standard OTLP, and no vendor-specific
configuration is added.

Rationale for this change

Operators asked whether PowerContext traces can be viewed in Langfuse, which adds cost accounting, a metrics API, and
metadata filtering on top of the span tree that the Phoenix guide already documents. The verification showed that the
existing OTLP export works unchanged: Langfuse ingests every PowerContext span through its OTLP endpoint when the
standard OpenTelemetry environment variables carry the Langfuse endpoint and Basic-auth header. The only missing piece
was documentation.

The .env.example OTLP endpoint example also carried a /v1/traces suffix that the OpenTelemetry HTTP exporter
appends again (_append_trace_path() in opentelemetry-exporter-otlp-proto-http 1.43.0), which would send spans to
/v1/traces/v1/traces.

What changes are included in this PR?

  • New how-to guide docs/en/docs/how-to/trace-with-langfuse.md and its Chinese translation
    docs/zh/docs/how-to/trace-with-langfuse.md, structured like the Phoenix guide: start Langfuse, install the
    tracing-otlp extra, configure the exporter with OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_EXPORTER_OTLP_HEADERS,
    trigger one flush, read the resulting observations (types, names, metadata, request-ID filtering, cost), what is
    not exported, stop Langfuse.
  • One cross-reference sentence in the OpenTelemetry section of docs/en/docs/reference/configuration.md and
    docs/zh/docs/reference/configuration.md.
  • .env.example: the OTEL_EXPORTER_OTLP_ENDPOINT example is now a base URL with a comment that the SDK appends
    /v1/traces.

No code, dependency, span name, or attribute changes.

Are there any user-facing changes?

Documentation only. The .env.example change corrects a commented-out example value; it does not change runtime
behavior.

How was this change tested?

  • make check (lock consistency, prek hooks, ty) passed.
  • make docs-test (oxlint plus the Next.js static export and its verification) passed on top of 74b961fb; both new
    pages are generated and listed in the how-to sidebar.
  • uv run pytest tests/test_server_tracing.py tests/e2e/test_observability.py: 24 passed. The default test suite still
    needs no telemetry backend.
  • Manual end-to-end verification against a local Langfuse 4.10.0 (Docker Compose) with PowerContext at f0f288ab:
    one Server run without a generation model and one with Pydantic AI's test model, driving HTTP (/v1/sources/content,
    /v1/memory/flush, /v1/memory/remember, /v1/memory/search, /v1/context/prepare) and MCP (list_memory_entries)
    requests. Exported observations were read back through GET /api/public/v2/observations: 67 observations across 19
    traces, all PowerContext spans ingested as SPAN, invoke_agent as AGENT, chat <model> as GENERATION with
    model name and token usage, FastMCP tool spans as TOOL; failed operations mapped to level=ERROR with
    error.type; attributes.powercontext.request.id filterable through the metadata filter. A grep of the exported
    JSON found no Memory or Source content, search queries, scope_id, authorization headers, or keys; generation
    input/output contain message shapes only.
  • Not verified: a real provider model (TestModel was used), embedding spans, the Langfuse UI navigation labels (API
    only), and Langfuse Cloud.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant