GoodMemGoodMem
IntegrationsObservability & Eval

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=parent

The 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=4

The 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 start

For a direct JVM launch, export the same variables before the server starts.

Verify the observations

  1. Send the verification request.
  2. Find the request in the intended Langfuse project.
  3. Match its request_id metadata with the response goodmem-request-id header.
  4. If you have a populated space, run one retrieval.
  5. Inspect its retrieval and provider observations.
GoodMem operationLangfuse observation type
Retrievalretriever
Retrieval stagespan
Embeddingembedding
Rerankspan
Typed LLM callgeneration

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.

On this page