Langfuse
Export GoodMem server traces to Langfuse with the native OTLP endpoint.
Langfuse
GoodMem exports server traces directly to Langfuse through OTLP/HTTP. The langfuse profile adds observation types and selected metadata to each span.
You need a Langfuse project, its public and secret keys, and access to the GoodMem server configuration.
For collector fan-out, follow Export traces from GoodMem with the neutral profile.
Configure the endpoint
Set these variables in the GoodMem server environment:
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=none
OTEL_LOGS_EXPORTER=none
OTEL_SERVICE_NAME=goodmem-server
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://cloud.langfuse.com/api/public/otel/v1/traces
GOODMEM_OTEL_EXPORT_PROFILE=langfuse
GOODMEM_OTEL_REMOTE_PARENT=parentThe example selects the EU cloud endpoint and overrides the SDK default protocol, grpc, which Langfuse rejects.
For another region or a self-hosted deployment, use its complete trace endpoint from the Langfuse endpoint reference.
Prepare the header file
See the installation directory for the location of .env.
Supply LANGFUSE_PUBLIC_KEY and LANGFUSE_SECRET_KEY through your secret manager.
Create the authentication token:
printf '%s' "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" | base64 | tr -d '\n' | sed 's/+/%2B/g'In the installation's private .env file, replace <token> with that output:
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authorization=Basic%20<token>,x-langfuse-ingestion-version=4The recipe encodes literal plus signs as %2B; the header uses %20 for the space after Basic.
Keep .env outside version control; the header value contains credentials.
Apply the configuration
Restart the installation:
goodmem system stop
goodmem system startFor a direct JVM launch, export the same variables before the server starts.
Verify the observations
- Send the verification request.
- Find the request in the intended Langfuse project.
- Match its
request_idmetadata with the responsegoodmem-request-idheader. - If you have a populated space, run one retrieval.
- Inspect its retrieval and provider observations.
| GoodMem operation | Langfuse observation type |
|---|---|
| Retrieval | retriever |
| Retrieval stage | span |
| Embedding | embedding |
| Rerank | span |
| Typed LLM call | generation |
Only executed stages appear. For empty input and output panels, see the trace data controls.
Trace names and counts
The default parent policy joins the caller's trace. GoodMem names its own observations without
assigning a name to the caller's trace. Without a remote parent, GoodMem names the new trace after
the request and includes that name on its child observations.
A valid traceparent from a proxy or gateway also joins an upstream trace, even if that system
exports nothing to Langfuse. GoodMem still exports sampled spans, but supplies no Langfuse trace
name for them. Name-filtered views and dashboards grouped by trace name can exclude those observations.
Use GOODMEM_OTEL_REMOTE_PARENT=link when you want separate GoodMem request traces with their own
names. This keeps a causal link to the caller, but separates the trees and samples locally instead
of inheriting the caller's sampling decision.
The dashboard counts distinct traces, not calls: five creates in one trace count as one trace.
For call counts, count API observations by operation; do not count their children again.
Sampling can omit requests. GoodMem does not import caller names from baggage, so its observations
in a shared trace do not include a caller-provided trace name.
Filter observations
The profile maps selected canonical fields into langfuse.observation.metadata.* attributes.
Useful metadata fields include request_id, principal_id, space_id, operation, outcome, failure_category, and failure_origin.
Langfuse scalar metadata uses strings for numeric and boolean values, but space ID lists remain arrays.
Metadata describes each observation, so a child result count and a request result count can use different units. Principal IDs appear as metadata rather than application-user or session fields. See the generated mappings for the field list and result counts for their units.
Interpret usage and cost
Cohere rerank billing quantities appear as cohere_search_units in observation/run metadata,
backed by goodmem.rerank.cohere.search_units. These preserve reported billing units independently
of token counts; they do not supply an automatically calculated price.
GoodMem exports provider-reported LLM usage and supported embedding and rerank input counts.
The profile preserves gen_ai.usage.input_tokens, including explicitly reported zero.
If the attribute is absent, a zero displayed by Langfuse means unknown usage.
The profile maps reported total, cached-input, and reasoning-output counts to Langfuse's recognized
usage keys, preserving cache/reasoning subsets without double counting. It uses an available
response model for langfuse.observation.model.name. See the
local-provider mapping table.
Langfuse calculates model costs from usage and matching prices.
For a model missing from its catalog, configure a custom model price.
The home-page model-cost table excludes generic span observations, including reranks, even when
usage is stored. Inspect the rerank observation or query the metrics API with view=observations
and dimension providedModelName. A configured price does not change the widget's type filter;
cost availability elsewhere depends on the backend's pricing support.
GoodMem does not estimate token counts or monetary cost.
Diagnose missing traces
Check the region, protocol, complete endpoint, and encoded authentication value first. For local containers, check the collector or backend address from the server network. See Troubleshoot tracing for the delivery checks.
GoodMem does not export LLM answer text. The export boundary also removes known GenAI/OpenInference
prompt, completion, tool-content attributes and message/choice events if another instrumentor adds
them. Token counts, response-shape flags, and provider timing metadata remain available. Optional
llama.cpp, Ollama, and vLLM generation measurements appear as llama_cpp_*, ollama_*, and vllm_* metadata; these diagnostics
do not replace client-observed latency or supply additional token consumption.