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

TraceEvent

org.llm4s.trace.TraceEvent
See theTraceEvent companion trait
object TraceEvent

Attributes

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

Members list

Type members

Classlikes

final case class AgentInitialized extends TraceEvent

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object AgentInitialized

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class AgentRunEnded extends TraceEvent

An agent run ended. Emitted once per run, from the run's own final state, by the agent's tracing; it carries the turn's conversation for backends that record it (Langfuse turns it into a trace with one span per message). A blocked turn has been removed from the thread by then, so a blocked run carries no messages.

An agent run ended. Emitted once per run, from the run's own final state, by the agent's tracing; it carries the turn's conversation for backends that record it (Langfuse turns it into a trace with one span per message). A blocked turn has been removed from the thread by then, so a blocked run carries no messages.

Value parameters

agent

the agent active when the run ended

messages

this turn's messages, from its user message on; empty when blocked, cancelled, timed out or failed. Not included in toJson, which stays a flat summary.

parentRunId

for a delegated child run, the parent run that started it; None for a top-level run

parentThreadId

for a delegated child run, the thread of the parent whose tool call started it; None for a top-level run

provider

the canonical id of the provider of the run's model calls (the first call's, when they used several), when its client reported one; OpenTelemetry's gen_ai.provider.name

runId

this run

span

the run's own span (design 4.58): its context, its parent - a child run's is the task tool call that started it, a continued run's the context it continued - and when the run started

status

completed, suspended, step_limit_reached, blocked:<guardrail>, cancelled, timed_out or failed

threadId

the conversation's thread; backends use it as the session

usage

this run's own token usage and cost, per model: the model calls the run made, never the thread's earlier runs, so a backend can report it per run (as OpenTelemetry's per-operation gen_ai.usage.*) without double counting

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object AgentRunEnded

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class CacheHit extends TraceEvent

Cache hit event for semantic caching

Cache hit event for semantic caching

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object CacheHit

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
CacheHit.type
final case class CacheMiss extends TraceEvent

Cache miss event for semantic caching

Cache miss event for semantic caching

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object CacheMiss

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
CacheMiss.type
object CacheMissReason

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait CacheMissReason

Cache miss reason ADT

Cache miss reason ADT

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object LowSimilarity
object TtlExpired
final case class CompletionReceived extends TraceEvent

A model returned a completion. A client wrapped in TracingLLMClient fills in the call's details as well, which a backend that follows the OpenTelemetry GenAI conventions reports on the call's chat <model> span (#2275).

A model returned a completion. A client wrapped in TracingLLMClient fills in the call's details as well, which a backend that follows the OpenTelemetry GenAI conventions reports on the call's chat <model> span (#2275).

Value parameters

content

the completion's text: message content, which backends record only when told to

duration

how long the call took; the event's timestamp is its end

finishReasons

why the model stopped, as the provider reported it

id

the completion's id (gen_ai.response.id)

input

the request's messages: message content, which backends record only when told to; not included in toJson

model

the requested model (gen_ai.request.model)

options

the options the request was sent with

provider

the canonical id of the provider called (openai, anthropic, ...), when known

responseModel

the model that answered, when the provider reported it

serverAddress

the host the request went to, when known

streamed

whether the completion was streamed (streamComplete)

toolCalls

how many tool calls the completion asked for

usage

the call's token usage, when the provider reported it

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object CompletionReceived

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class CostRecorded extends TraceEvent

Tracks cost in USD for any model operation.

Tracks cost in USD for any model operation.

Value parameters

costType

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

costUsd

Estimated cost in US dollars

model

Model name used for pricing lookup

operation

Type of operation: "embedding", "completion", "evaluation"

tokenCount

Total tokens consumed

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object CostRecorded

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class CustomEvent extends TraceEvent

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object CustomEvent

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class EmbeddingUsageRecorded extends TraceEvent

Tracks embedding token usage for cost analysis. An org.llm4s.llmconnect.EmbeddingClient emits one per call, which a backend that follows the OpenTelemetry GenAI conventions reports as the call's embeddings <model> span (#2275).

Tracks embedding token usage for cost analysis. An org.llm4s.llmconnect.EmbeddingClient emits one per call, which a backend that follows the OpenTelemetry GenAI conventions reports as the call's embeddings <model> span (#2275).

Value parameters

duration

how long the call took; the event's timestamp is its end

inputCount

Number of texts embedded in this operation

model

Embedding model name (e.g., "text-embedding-3-small")

operation

Type of operation: "indexing", "query", "evaluation"

provider

the canonical id of the provider called (openai, voyage, ...), when known

usage

Token usage statistics from embedding operation

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object EmbeddingUsageRecorded

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class ErrorOccurred extends TraceEvent

An error. When it is a failed model call - a TracingLLMClient's, or an org.llm4s.llmconnect.EmbeddingClient's - operation names the call (chat, embeddings) and the call's details are set, which a backend that follows the OpenTelemetry GenAI conventions reports as the call's own span with error.type (#2275).

An error. When it is a failed model call - a TracingLLMClient's, or an org.llm4s.llmconnect.EmbeddingClient's - operation names the call (chat, embeddings) and the call's details are set, which a backend that follows the OpenTelemetry GenAI conventions reports as the call's own span with error.type (#2275).

Value parameters

duration

how long the failed call took; the event's timestamp is its end

errorType

a short, low-cardinality name of the failure (the LLMError's type, e.g. RateLimitError); None takes the exception's class name

model

the requested model of the failed call

operation

the GenAI operation that failed (chat, embeddings); None for any other error

provider

the canonical id of the provider called

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object ErrorOccurred

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class ImageGenerationCompleted extends TraceEvent

Tracks completion of an image generation operation.

Tracks completion of an image generation operation.

Value parameters

costUsd

Estimated cost in USD, if available

duration

Wall-clock duration

errorMessage

Error message if the operation failed

imageCount

Number of images generated

model

Image generation model name (e.g., "gpt-image-1", "dall-e-3")

operation

Type of operation: "generate", "edit"

provider

Provider name (e.g., "openai", "stability-ai")

quality

Quality level (e.g., "standard", "hd")

size

Image size descriptor (e.g., "1024x1024")

success

Whether the operation succeeded

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object ImageGenerationCompleted

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class RAGOperationCompleted extends TraceEvent

Tracks completion of a RAG operation with full metrics.

Tracks completion of a RAG operation with full metrics.

Value parameters

duration

Wall-clock duration

embeddingTokens

Optional token count for embedding operations

llmCompletionTokens

Optional completion tokens for LLM operations

llmPromptTokens

Optional prompt tokens for LLM operations

operation

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

totalCostUsd

Optional accumulated cost in USD

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object RAGOperationCompleted

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class TokenUsageRecorded extends TraceEvent

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object TokenUsageRecorded

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
final case class ToolExecuted extends TraceEvent

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
trait TraceEvent
class Object
trait Matchable
class Any
Show all
object ToolExecuted

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type

Inherited and Abstract types

type MirroredElemLabels <: Tuple

The names of the product elements

The names of the product elements

Attributes

Inherited from:
Mirror
type MirroredLabel <: String

The name of the type

The name of the type

Attributes

Inherited from:
Mirror
Generated with