docs(tracing): add Langfuse tracing guide and fix OTLP endpoint example - #1471
Open
Ethan-Xingyue wants to merge 2 commits into
Open
docs(tracing): add Langfuse tracing guide and fix OTLP endpoint example#1471Ethan-Xingyue wants to merge 2 commits into
Ethan-Xingyue wants to merge 2 commits into
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 stayswithin 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.exampleOTLP endpoint example also carried a/v1/tracessuffix that the OpenTelemetry HTTP exporterappends again (
_append_trace_path()inopentelemetry-exporter-otlp-proto-http1.43.0), which would send spans to/v1/traces/v1/traces.What changes are included in this PR?
docs/en/docs/how-to/trace-with-langfuse.mdand its Chinese translationdocs/zh/docs/how-to/trace-with-langfuse.md, structured like the Phoenix guide: start Langfuse, install thetracing-otlpextra, configure the exporter withOTEL_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.
docs/en/docs/reference/configuration.mdanddocs/zh/docs/reference/configuration.md..env.example: theOTEL_EXPORTER_OTLP_ENDPOINTexample 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.examplechange corrects a commented-out example value; it does not change runtimebehavior.
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 of74b961fb; both newpages 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 stillneeds no telemetry backend.
f0f288ab:one Server run without a generation model and one with Pydantic AI's
testmodel, 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 19traces, all PowerContext spans ingested as
SPAN,invoke_agentasAGENT,chat <model>asGENERATIONwithmodel name and token usage, FastMCP tool spans as
TOOL; failed operations mapped tolevel=ERRORwitherror.type;attributes.powercontext.request.idfilterable through the metadata filter. A grep of the exportedJSON found no Memory or Source content, search queries,
scope_id, authorization headers, or keys; generationinput/output contain message shapes only.
only), and Langfuse Cloud.