Langfuse Tracing implementation for production observability.
Sends trace events to Langfuse for centralized observability, debugging, and LLM application monitoring. Supports all trace event types with type-safe Result[Unit] return values.
== Features ==
Real-time event streaming to Langfuse
Hierarchical trace structure (traces with child spans)
Token usage and cost tracking
Error logging with stack traces
Agent state snapshots with conversation history
== Configuration ==
Configure via environment variables or direct instantiation:
// Environment variables
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_URL=https://cloud.langfuse.com (optional)
// Or programmatic configuration
val tracing = new LangfuseTracing(
langfuseUrl = "https://cloud.langfuse.com",
publicKey = Secret("pk-lf-..."),
secretKey = Secret("sk-lf-..."),
environment = "production",
release = "1.0.0",
version = "1.0.0"
)
The ConsoleTracing and LangfuseTracing implementations emit a TraceEvent.CompletionReceived event containing the completion ID, the supplied model identifier, the number of tool calls in the assistant message, and the message content.
Implementations should report tracing failures through the returned result rather than throwing exceptions.
Value parameters
completion
the model response whose details are to be traced
model
the model identifier to associate with this completion
Attributes
Returns
Right(()) when the tracing call is handled successfully, including when a no-op backend discards it, or Left(error) if tracing fails. Callers may ignore or log tracing failures.
Records an error together with context describing where it occurred.
Records an error together with context describing where it occurred.
The ConsoleTracing and LangfuseTracing implementations emit a TraceEvent.ErrorOccurred event containing the supplied error and context.
Implementations should report tracing failures through the returned result rather than throwing exceptions.
Value parameters
context
a description of the operation or circumstances in which the error occurred, such as "fetching weather data"; defaults to an empty string
error
the error to record
Attributes
Returns
Right(()) when the tracing call is handled successfully, including when a no-op backend discards it, or Left(error) if tracing fails. Callers may ignore or log tracing failures.
Handles a structured trace event using this tracing backend. Implementations should report tracing failures through the returned result rather than throwing exceptions.
Handles a structured trace event using this tracing backend. Implementations should report tracing failures through the returned result rather than throwing exceptions.
Value parameters
event
the structured event to trace
Attributes
Returns
Right(()) when the tracing call is handled successfully, including when a no-op backend discards the event, or Left(error) if tracing fails. Callers may ignore or log tracing failures.
The ConsoleTracing and LangfuseTracing implementations emit a TraceEvent.TokenUsageRecorded event containing the supplied usage, model identifier, and operation label.
Implementations should report tracing failures through the returned result rather than throwing exceptions.
Value parameters
model
the model identifier to associate with this usage
operation
a caller-defined label describing the operation, such as "completion"
usage
the token usage reported for the operation
Attributes
Returns
Right(()) when the tracing call is handled successfully, including when a no-op backend discards it, or Left(error) if tracing fails. Callers may ignore or log tracing failures.
Records a tool call using the supplied tool name, input, and output.
Records a tool call using the supplied tool name, input, and output.
The ConsoleTracing and LangfuseTracing implementations emit a TraceEvent.ToolExecuted event with zero duration and the success flag set to true. They do not measure the duration or determine whether the tool execution succeeded.
Implementations should report tracing failures through the returned result rather than throwing exceptions.
Value parameters
input
the input supplied to the tool
output
the output returned by the tool
toolName
the name of the tool that was called
Attributes
Returns
Right(()) when the tracing call is handled successfully, including when a no-op backend discards it, or Left(error) if tracing fails. Callers may ignore or log tracing failures.
Emits a named CustomEvent with no additional data payload.
Emits a named CustomEvent with no additional data payload.
Wraps the string in a TraceEvent.CustomEvent with an empty JSON object as its data field before delegating to traceEvent(TraceEvent). Use the typed overload for events that carry structured data.
Value parameters
event
Human-readable event name forwarded as CustomEvent.name