llm4s-docs
API
Generated with
llm4s-docs/org.llm4s/org.llm4s.trace/Tracing

Tracing

org.llm4s.trace.Tracing
See theTracing companion object
@Stable
trait Tracing

Type-safe tracing interface for observability and debugging.

Provides a functional approach to tracing with Result[Unit] return types for proper error handling and composition. Supports multiple backends including console output, Langfuse, OpenTelemetry and custom implementations.

== Implementations ==

  • ConsoleTracing - Colored console output for development (core); metadata only unless llm4s.tracing.console.captureContent is set
  • NoOpTracing - Silent implementation for testing/disabled tracing (core)
  • LangfuseTracing - Production observability via Langfuse (llm4s-observability)
  • OpenTelemetryTracing - OTLP export (llm4s-observability-otel)

== Usage ==

// Create from settings
val tracing = Tracing.create(settings)

// Or use directly
val tracing: Tracing = new ConsoleTracing()

// Trace events functionally
for {
 _ <- tracing.traceEvent(TraceEvent.AgentInitialized("query", tools))
 _ <- tracing.traceTokenUsage(usage, "gpt-4", "completion")
} yield ()

== Agent state ==

There is no traceAgentState(AgentState). An agent run reports its end with TraceEvent.AgentRunEnded; the agent's per-step events arrive as CustomEvents named graph.* and agent.*.

== Composition ==

Tracers can be composed using TracingComposer:

val combined = TracingComposer.combine(consoleTracer, langfuseTracer)
val filtered = TracingComposer.filter(tracer)(_.eventType == "error_occurred")

Attributes

See also

TraceEvent for available event types

TracingComposer for composition utilities

Companion
object
Graph
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class NoOpTracing

Members list

Value members

Abstract methods

def traceCompletion(completion: Completion, model: String): Result[Unit]

Records a completion received from a model.

Records a completion received from a model.

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.

def traceError(error: Throwable, context: String): Result[Unit]

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.

def traceEvent(event: TraceEvent): Result[Unit]

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.

def traceTokenUsage(usage: TokenUsage, model: String, operation: String): Result[Unit]

Records token usage for a model operation.

Records token usage for a model operation.

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.

def traceToolCall(toolName: String, input: String, output: String): Result[Unit]

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.

Concrete methods

def shutdown(): Unit

Shutdown the tracing backend. Alias for close() to maintain terminology consistency.

Shutdown the tracing backend. Alias for close() to maintain terminology consistency.

Attributes

final def traceCost(costUsd: Double, model: String, operation: String, tokenCount: Int, costType: String): Result[Unit]

Trace cost in USD for any operation.

Trace cost in USD for any operation.

Value parameters

costType

Category: "embedding", "completion", "total"

costUsd

Cost in US dollars

model

Model name

operation

Type: "embedding", "completion", "evaluation"

tokenCount

Total tokens used

Attributes

final def traceEmbeddingUsage(usage: EmbeddingUsage, model: String, operation: String, inputCount: Int): Result[Unit]

Trace embedding token usage for cost tracking.

Trace embedding token usage for cost tracking.

Value parameters

inputCount

Number of texts embedded

model

Embedding model name

operation

Type: "indexing", "query", "evaluation"

usage

Token usage from embedding operation

Attributes

final def traceEvent(event: String): Result[Unit]

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

Attributes

final def traceRAGOperation(operation: String, duration: FiniteDuration, embeddingTokens: Option[Int], llmPromptTokens: Option[Int], llmCompletionTokens: Option[Int], totalCostUsd: Option[Double]): Result[Unit]

Trace completion of a RAG operation with metrics.

Trace completion of a RAG operation with metrics.

Value parameters

duration

Wall-clock duration

embeddingTokens

Optional embedding token count

llmCompletionTokens

Optional LLM completion tokens

llmPromptTokens

Optional LLM prompt tokens

operation

Type: "index", "search", "answer", "evaluate"

totalCostUsd

Optional total cost in USD

Attributes

Generated with