Package com.tnsai.llm.observability

Record Class LLMCallLog

java.lang.Object
java.lang.Record
com.tnsai.llm.observability.LLMCallLog
public record LLMCallLog(String callId, Instant startedAt, Instant completedAt, Duration elapsed, String provider, String model, String endpoint, com.tnsai.observability.events.EventContext context, LLMPrompt prompt, ToolSurface tools, LLMResponse response, TokenUsage usage, CostEstimate cost, com.tnsai.llm.ChatChunk.FinishReason finishReason, Optional<StreamMetrics> streamMetrics, Optional<ErrorInfo> error, int retryAttempt, Map<String,Object> providerExtensions) extends Record
One observed LLM call, end-to-end (issue #79).

Captures everything an operator needs to answer the "what happened on this call?" questions:

  • Routing — which provider + model + endpoint
  • Identity — which tenant / agent / capability called (EventContext)
  • Input — the typed LLMPrompt + ToolSurface
  • Output — typed LLMResponse + TokenUsage + CostEstimate + ChatChunk.FinishReason
  • Stream timing — optional StreamMetrics for streaming calls (TTFT, inter-chunk percentiles)
  • Errors — optional ErrorInfo for failed calls, plus retryAttempt count
  • Provider-specific extensions — opaque bag for things that don't fit the typed shape (Anthropic stop_reason variants, OpenAI request fingerprints, etc.)

This record is the data shape only. Wiring it into AbstractLLMClient so every provider auto-emits one per call is a focused follow-up — that change touches every provider's chat / streamChat hot path and deserves its own PR with regression tests. Same goes for the Prometheus derivation + SLF4J / OTel publication path.

Privacy: the record holds raw prompt + response text. Production deployments must route this through the redaction SPI (issue #80, not yet built) before persisting or shipping to external trackers (LangFuse, Helicone, Phoenix). The capture wrapper is responsible for that — this record itself stays unaware of redaction.

Since:
0.5.0 (issue #79)

  • Constructor Details

    • LLMCallLog

      public LLMCallLog(String callId, Instant startedAt, Instant completedAt, Duration elapsed, String provider, String model, String endpoint, com.tnsai.observability.events.EventContext context, LLMPrompt prompt, ToolSurface tools, LLMResponse response, TokenUsage usage, CostEstimate cost, com.tnsai.llm.ChatChunk.FinishReason finishReason, Optional<StreamMetrics> streamMetrics, Optional<ErrorInfo> error, int retryAttempt, Map<String,Object> providerExtensions)
      Creates an instance of a LLMCallLog record class.
      Parameters:
      callId - the value for the callId record component
      startedAt - the value for the startedAt record component
      completedAt - the value for the completedAt record component
      elapsed - the value for the elapsed record component
      provider - the value for the provider record component
      model - the value for the model record component
      endpoint - the value for the endpoint record component
      context - the value for the context record component
      prompt - the value for the prompt record component
      tools - the value for the tools record component
      response - the value for the response record component
      usage - the value for the usage record component
      cost - the value for the cost record component
      finishReason - the value for the finishReason record component
      streamMetrics - the value for the streamMetrics record component
      error - the value for the error record component
      retryAttempt - the value for the retryAttempt record component
      providerExtensions - the value for the providerExtensions record component

  • Method Details

    • isFailure

      public boolean isFailure()
      true when this call ended in ErrorInfo.

    • isStreamed

      public boolean isStreamed()
      true when streaming-specific metrics were recorded.

    • providerModel

      public String providerModel()
      Stable identifier of the (provider, model) pair — useful as a Prometheus label and as a dashboard group key.

    • builder

      public static LLMCallLog.Builder builder()
      Returns a builder pre-populated with the minimum required fields. Callers fill in input / output / cost as the call progresses.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • callId

      public String callId()
      Returns the value of the callId record component.
      Returns:
      the value of the callId record component

    • startedAt

      public Instant startedAt()
      Returns the value of the startedAt record component.
      Returns:
      the value of the startedAt record component

    • completedAt

      public Instant completedAt()
      Returns the value of the completedAt record component.
      Returns:
      the value of the completedAt record component

    • elapsed

      public Duration elapsed()
      Returns the value of the elapsed record component.
      Returns:
      the value of the elapsed record component

    • provider

      public String provider()
      Returns the value of the provider record component.
      Returns:
      the value of the provider record component

    • model

      public String model()
      Returns the value of the model record component.
      Returns:
      the value of the model record component

    • endpoint

      public String endpoint()
      Returns the value of the endpoint record component.
      Returns:
      the value of the endpoint record component

    • context

      public com.tnsai.observability.events.EventContext context()
      Returns the value of the context record component.
      Returns:
      the value of the context record component

    • prompt

      public LLMPrompt prompt()
      Returns the value of the prompt record component.
      Returns:
      the value of the prompt record component

    • tools

      public ToolSurface tools()
      Returns the value of the tools record component.
      Returns:
      the value of the tools record component

    • response

      public LLMResponse response()
      Returns the value of the response record component.
      Returns:
      the value of the response record component

    • usage

      public TokenUsage usage()
      Returns the value of the usage record component.
      Returns:
      the value of the usage record component

    • cost

      public CostEstimate cost()
      Returns the value of the cost record component.
      Returns:
      the value of the cost record component

    • finishReason

      public com.tnsai.llm.ChatChunk.FinishReason finishReason()
      Returns the value of the finishReason record component.
      Returns:
      the value of the finishReason record component

    • streamMetrics

      public Optional<StreamMetrics> streamMetrics()
      Returns the value of the streamMetrics record component.
      Returns:
      the value of the streamMetrics record component

    • error

      public Optional<ErrorInfo> error()
      Returns the value of the error record component.
      Returns:
      the value of the error record component

    • retryAttempt

      public int retryAttempt()
      Returns the value of the retryAttempt record component.
      Returns:
      the value of the retryAttempt record component

    • providerExtensions

      public Map<String,Object> providerExtensions()
      Returns the value of the providerExtensions record component.
      Returns:
      the value of the providerExtensions record component