org.llm4s.trace

@Stable

ANSI escape codes for terminal color formatting.

Provides a centralized set of color constants used by console-based tracing implementations for improved readability during development and debugging.

Attributes

Note

These codes work on most Unix terminals and Windows Terminal. They may not render correctly in non-ANSI-compatible environments.

Example

import org.llm4s.trace.AnsiColors._
println(s"$${GREEN}Success!$${RESET}")
println(s"$${RED}$${BOLD}Error: Something failed$${RESET}")

Supertypes

class Object

trait Matchable

class Any

Self type

AnsiColors.type

@Stable

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.

== 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()

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

Attributes

See also: NoOpTracing for silent tracing

LangfuseTracing in llm4s-observability for production observability

AnsiColors for color constants used
Supertypes: trait Tracing

class Object

trait Matchable

class Any

Default implementation of LangfuseBatchSender using HTTP requests.

Sends trace events to Langfuse using basic authentication with the provided public and secret keys. A 2xx response is a success; a 207 Multi-Status response is read per event, and any events it lists as rejected are logged as an error.

Logs warnings if credentials are not configured and errors if the HTTP request fails.

Attributes

Companion: object
Supertypes: trait LangfuseBatchSender

class Object

trait Matchable

class Any

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: DefaultLangfuseBatchSender.type

Abstraction for sending trace events to Langfuse in batches.

Implementations handle the HTTP communication with the Langfuse API, including authentication, error handling, and logging.

Attributes

See also: DefaultLangfuseBatchSender for the standard implementation
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class DefaultLangfuseBatchSender

Configuration for calling the Langfuse HTTP API.

Value parameters

langfuseUrl: Base URL of the Langfuse API endpoint
publicKey: Langfuse public key for authentication
secretKey: Langfuse secret key for authentication

Attributes

Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all

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 = "pk-lf-...",
 secretKey = "sk-lf-...",
 environment = "production",
 release = "1.0.0",
 version = "1.0.0"
)

== Usage ==

val tracing: Tracing = LangfuseTracing.from(config)

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

Value parameters

environment: Environment name (e.g., "production", "staging")
langfuseUrl: Langfuse API URL (default: https://cloud.langfuse.com)
publicKey: Langfuse public key for authentication
release: Release/version identifier
secretKey: Langfuse secret key for authentication
version: API version

Attributes

See also: ConsoleTracing for local development

NoOpTracing for disabled tracing

TracingMode for configuration modes
Companion: object
Supertypes: trait Tracing

class Object

trait Matchable

class Any

Factory methods for LangfuseTracing.

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: LangfuseTracing.type

Registers LangfuseTracing for TracingMode.Named("langfuse") (TRACING_MODE=langfuse).

Declared in llm4s-observability's META-INF/services/org.llm4s.trace.spi.TracingBackend, so depending on the module is all it takes. It reads its settings from settings.extras - the llm4s.tracing.langfuse block, which this module's reference.conf binds to the LANGFUSE_* variables - as a provider descriptor reads its named section.

Without both keys it refuses to start, so Tracing.fromSettings reports the missing variables and Tracing.create falls back to NoOpTracing with that error logged, rather than returning a tracer that drops every batch.

A class rather than an object because java.util.ServiceLoader instantiates it through a public no-arg constructor.

Attributes

Supertypes: trait TracingBackend

class Object

trait Matchable

class Any

@Stable

No-operation Tracing implementation that silently discards all events.

All methods return Right(()) immediately without performing any operations. Use this implementation when tracing is disabled or not needed.

== Usage ==

val tracing: Tracing = new NoOpTracing()

// All operations succeed silently
tracing.traceEvent(TraceEvent.CustomEvent("test", ujson.Obj())) // Returns Right(())
tracing.traceError(new Exception("ignored")) // Returns Right(())

== Use Cases ==

Production environments where tracing overhead is undesirable
Unit tests that don't need trace output
Default fallback when no tracing is configured

Attributes

See also: ConsoleTracing for development/debugging

LangfuseTracing in llm4s-observability for production observability
Supertypes: trait Tracing

class Object

trait Matchable

class Any

Attributes

Companion: object
Supertypes: trait Tracing

class Object

trait Matchable

class Any

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: OpenTelemetryTracing.type

Registers OpenTelemetryTracing for TracingMode.Named("opentelemetry") (TRACING_MODE=opentelemetry or otel).

Declared in this module's META-INF/services/org.llm4s.trace.spi.TracingBackend, so depending on llm4s-observability-otel is all it takes; Tracing.create finds it by ServiceLoader. That replaced the Class.forName reflection core used to load this module (#1133).

A class rather than an object because java.util.ServiceLoader instantiates it through a public no-arg constructor.

Attributes

Supertypes: trait TracingBackend

class Object

trait Matchable

class Any

A Tracing implementation that converts every TraceEvent into a Span and persists it in the given TraceStore[F].

Composable with other backends via TracingComposer.combine(). The traceId field exposes the identifier assigned to this run so callers can retrieve spans from the store after execution completes.

Type parameters

F: effect type of the backing store; an implicit org.llm4s.util.LiftToResult instance must be available to bridge F[A] into Result[A]

Value parameters

initialTraceId: optional fixed trace ID; a random UUID is used when absent
store: destination for all recorded spans

Attributes

Companion: object
Supertypes: trait Tracing

class Object

trait Matchable

class Any

Attributes

Companion: class
Supertypes: class Object

trait Matchable

class Any
Self type: TraceCollectorTracing.type

@Stable

Type-safe, sealed hierarchy of trace events emitted during LLM agent execution.

Each subtype carries the data relevant to one observable moment in the agent lifecycle (completion received, tool executed, token usage recorded, etc.). All subtypes are serialisable to JSON via toJson, which produces a flat object containing at minimum "event_type" and "timestamp" fields.

== Error truncation == ErrorOccurred.toJson includes only the first 5 frames of the stack trace to limit payload size.

== Timestamp default == Every case class defaults timestamp to Instant.now() at construction time. Override explicitly when replaying historical events or writing deterministic tests.

Attributes

See also: Tracing for the interface that consumes these events
Companion: object
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class AgentInitialized

class AgentRunEnded

class CacheHit

class CacheMiss

class CompletionReceived

class CostRecorded

class CustomEvent

class EmbeddingUsageRecorded

class ErrorOccurred

class ImageGenerationCompleted

class RAGOperationCompleted

class TokenUsageRecorded

class ToolExecuted
Show all

Attributes

Companion: trait
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: TraceEvent.type

@Stable

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)
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
Supertypes: class Object

trait Matchable

class Any
Known subtypes: class ConsoleTracing

class LangfuseTracing

class NoOpTracing

class OpenTelemetryTracing

class TraceCollectorTracing[F]

Factory for creating Tracing instances.

// From TracingSettings: falls back to NoOp, with an error logged, if the backend is missing
val tracing = Tracing.create(settings)

// The same, but a missing or failing backend is an error the caller sees
val checked: Result[Tracing] = Tracing.fromSettings(settings)

// Direct instantiation
val console = new ConsoleTracing()
val noop = new NoOpTracing()

Attributes

See also: TracingMode for available modes

org.llm4s.trace.spi.TracingBackend for adding a backend
Companion: trait
Supertypes: class Object

trait Matchable

class Any
Self type: Tracing.type

@Stable

Utilities for composing multiple tracers.

Provides functional composition patterns for combining, filtering, and transforming trace events across multiple tracing backends.

== Combining Tracers ==

Send events to multiple backends simultaneously:

val combined = TracingComposer.combine(consoleTracer, langfuseTracer)
combined.traceEvent(event) // Sends to both

== Filtering Events ==

Only trace events matching a predicate:

val errorsOnly = TracingComposer.filter(tracer)(_.eventType == "error_occurred")

== Transforming Events ==

Modify events before tracing:

val enriched = TracingComposer.transform(tracer) {
 case e: TraceEvent.CustomEvent => e.copy(name = "prefix_" + e.name)
 case other => other
}

Attributes

Companion: object
Supertypes: class Object

trait Matchable

class Any
Known subtypes: object TracingComposer

Attributes

Companion: trait
Supertypes: trait TracingComposer

class Object

trait Matchable

class Any
Self type: TracingComposer.type

@Stable

Selects a tracing backend.

NoOp and Console are built by core itself, and are the only modes core has a case for. Every other mode is a TracingMode.Named served by a org.llm4s.trace.spi.TracingBackend found on the classpath: Named("langfuse") by llm4s-observability, Named("opentelemetry") by llm4s-observability-otel, and any third-party backend the same way (D2, #1133). TracingMode.Langfuse and TracingMode.OpenTelemetry were removed when their backends left core.

The TRACING_MODE environment variable (llm4s.tracing.mode) is the standard way to select a mode; see Llm4sConfig.tracing.

Attributes

Companion: object
Supertypes: trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any
Show all
Known subtypes: object Console

class Named

object NoOp

Attributes

Companion: trait
Supertypes: trait Sum

trait Mirror

class Object

trait Matchable

class Any
Self type: TracingMode.type

org.llm4s.trace

Members list

Packages

Type members

Classlikes

Attributes

Attributes

Attributes

Attributes

Attributes

Value parameters

Attributes

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Type parameters

Value parameters

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes

Attributes