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

ConsoleTracing

org.llm4s.trace.ConsoleTracing
See theConsoleTracing companion object
@Stable
class ConsoleTracing(val captureContent: Boolean) extends Tracing

Console-based Tracing implementation with colored, formatted output.

Prints trace events to standard output with ANSI color formatting for improved readability during development and debugging. Returns Result[Unit] to support functional composition.

== Content is withheld unless enabled ==

By default it prints metadata only: each event's type, timestamp, model, ids, tool names, success flags, durations, token counts and costs. Text that may hold personal or confidential data - the query of AgentInitialized, the content of CompletionReceived, the input and output of ToolExecuted, the field values of a CustomEvent (whose data is defined by whoever emits it, so may hold anything), and the message and context of an error - is replaced by [withheld: N chars] (a CustomEvent shows its field names). Standard output is often collected into logs kept outside the controls applied to the conversation itself (#2311).

Pass captureContent = true, or set llm4s.tracing.console.captureContent = true (LLM4S_TRACING_CONSOLE_CAPTURE_CONTENT=true) when the tracer is built from Llm4sConfig.tracing(), to print that text as well, truncated for readability.

== Features ==

  • Color-coded output by event type (errors in red, success in green, etc.)
  • Visual separators and headers for different trace sections
  • Formatted display of all TraceEvent types
  • Truncation of long JSON content for readability
  • Timestamps on all events

== Usage ==

val tracing: Tracing = new ConsoleTracing()            // metadata only
val verbose: Tracing = new ConsoleTracing(captureContent = true) // queries, answers, tool I/O too

// Trace events functionally
for {
 _ <- tracing.traceEvent(TraceEvent.AgentInitialized("query", Vector("tool1")))
 _ <- tracing.traceTokenUsage(TokenUsage(100, 50, 150), "gpt-4", "completion")
} yield ()

Value parameters

captureContent

print prompts, completions, tool input/output, custom event data and error messages; false (the default) prints metadata only

Attributes

See also

NoOpTracing for silent tracing

LangfuseTracing in llm4s-observability for production observability

AnsiColors for color constants used

Companion
object
Graph
Supertypes
trait Tracing
class Object
trait Matchable
class Any

Members list

Value members

Constructors

def this()

A console tracer that prints metadata only: no prompt, completion or tool content.

A console tracer that prints metadata only: no prompt, completion or tool content.

Attributes

Concrete 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.

Inherited 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

Inherited from:
Tracing
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

Inherited from:
Tracing
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

Inherited from:
Tracing
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

Inherited from:
Tracing
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

Inherited from:
Tracing

Concrete fields

val captureContent: Boolean
Generated with