Use Langfuse evidence to move from a broad symptom to the relevant trace, observation, session, prompt, or dataset. Start with the narrowest read-only query that can locate the event, then inspect its concrete inputs, outputs, timing, and errors.
Route the task
- For trace, observation, exception, latency, or session diagnosis, read diagnostic and management workflows.
- For installation, credentials, tool groups, output defaults, connection failures, or empty results, read setup.
- For exact parameters, filters, pagination, output modes, and response shapes, read the tool reference.
A common investigation starts with fetch_traces(age=60) or
find_exceptions(age=1440, group_by="file"), then fetches the selected trace or
observation by ID. Use full_json_file only when the complete payload is needed;
exports can contain sensitive user data.
Evidence and mutation boundaries
-
Treat model names, prompts, timestamps, and other values in historical traces as recorded evidence. Do not rewrite or normalize old model identifiers to a current name such as
gpt-6-astra. -
Trace discovery and inspection are read-only. Prompt creation or relabeling, dataset changes, annotation-queue changes, and deletions mutate Langfuse; perform them only when the user requested that change.
-
Prefer read-only server mode for diagnostic work. It disables prompt and dataset write tools:
langfuse-mcp --read-only # or LANGFUSE_MCP_READ_ONLY=true -
Never commit Langfuse credentials. Keep public key, secret key, and host in the supported environment or MCP configuration described in the setup reference. Rotate any exposed key.
-
Preserve exact IDs and filters in findings so another reader can reproduce the query. State when pagination, lookback limits, or compact output limits the conclusion.