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.

Only executed stages appear. For empty input and output panels, see the trace data controls.

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

GoodMem exports the LLM token counts that the provider reports. If the provider reports no count, Langfuse can show zero. Treat that zero as unknown. Langfuse calculates cost from the available usage and its own model catalog and prices.

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.