llm4s-core
API
Generated with
llm4s-core/org.llm4s/org.llm4s.trace

org.llm4s.trace

package org.llm4s.trace

Members list

Packages

package org.llm4s.trace.model
package org.llm4s.trace.store

Type members

Classlikes

object AnsiColors

ANSI escape codes for terminal color formatting.

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
class ConsoleTracing extends Tracing

Console-based Tracing implementation with colored, formatted output.

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 for production observability

AnsiColors for color constants used

Supertypes
trait Tracing
class Object
trait Matchable
class Any
class DefaultLangfuseBatchSender(httpClient: Llm4sHttpClient, restoreInterrupt: () => Unit) extends LangfuseBatchSender

Default implementation of LangfuseBatchSender using HTTP requests.

Default implementation of LangfuseBatchSender using HTTP requests.

Sends trace events to Langfuse using basic authentication with the provided public and secret keys. Handles both successful responses (200-299) and partial success responses (207).

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

Attributes

Supertypes
class Object
trait Matchable
class Any
trait LangfuseBatchSender

Abstraction for sending trace events to Langfuse in batches.

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
case class LangfuseHttpApiCaller(langfuseUrl: String, publicKey: String, secretKey: String)

Configuration for calling the Langfuse HTTP API.

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
class LangfuseTracing(langfuseUrl: String, publicKey: String, secretKey: String, environment: String, release: String, version: String, httpClient: Llm4sHttpClient, restoreInterrupt: () => Unit) extends Tracing

Langfuse Tracing implementation for production observability.

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
object LangfuseTracing

Factory methods for LangfuseTracing.

Factory methods for LangfuseTracing.

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
class NoOpTracing extends Tracing

No-operation Tracing implementation that silently discards all events.

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 for production observability

Supertypes
trait Tracing
class Object
trait Matchable
class Any
class TraceCollectorTracing[F[_]](store: TraceStore[F], initialTraceId: Option[TraceId])(implicit lift: LiftToResult[F]) extends Tracing

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

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
object TraceCollectorTracing

Attributes

Companion
class
Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait TraceEvent

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

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

TraceEvent.createTraceEvent for the Langfuse batch-envelope helper

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class CacheHit
class CacheMiss
class CostRecorded
class CustomEvent
class ToolExecuted
Show all
object TraceEvent

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
TraceEvent.type
trait Tracing

Type-safe tracing interface for observability and debugging.

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, and custom implementations.

== Implementations ==

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

== 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 NoOpTracing
object Tracing

Factory for creating Tracing instances.

Factory for creating Tracing instances.

Creates the appropriate tracing implementation based on configuration settings.

// From TracingSettings
val tracing = Tracing.create(settings)

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

Attributes

See also

TracingMode for available modes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
Tracing.type
trait TracingComposer

Utilities for composing multiple tracers.

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 extends TracingComposer

Attributes

Companion
trait
Supertypes
class Object
trait Matchable
class Any
Self type
sealed trait TracingMode extends Product, Serializable

Enumerates the available tracing backends.

Enumerates the available tracing backends.

Instances are created by Tracing.create based on the TracingSettings provided at startup. The TRACING_MODE environment variable is the standard way to select a mode; see Llm4sConfig for loading details.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
Known subtypes
object Console
object Langfuse
object NoOp
object OpenTelemetry
object TracingMode

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
Generated with