Package com.tnsai.llm.observability

Record Class TokenUsage

java.lang.Object
java.lang.Record
com.tnsai.llm.observability.TokenUsage
public record TokenUsage(long promptTokens, long completionTokens, long cachedTokens, long reasoningTokens, long totalTokens) extends Record
Token-count breakdown for one LLM call (issue #79).

Modern provider APIs (OpenAI o1, Anthropic Claude with thinking, prompt-caching APIs) report token counts split by purpose. cachedTokens captures prompt tokens served from a provider-side cache (priced lower); reasoningTokens captures reasoning-pass tokens for "thinking" models that count separately from the final completion. totalTokens is provider-reported when available, otherwise the caller computes it as promptTokens + completionTokens + reasoningTokens.

Since:
0.5.0 (issue #79)

  • Constructor Summary

    Constructors
    Constructor
    Description
    TokenUsage(long promptTokens, long completionTokens, long cachedTokens, long reasoningTokens, long totalTokens)
    Creates an instance of a TokenUsage record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    long
    cachedTokens()
    Returns the value of the cachedTokens record component.
    long
    completionTokens()
    Returns the value of the completionTokens record component.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    final int
    hashCode()
    Returns a hash code value for this object.
    static TokenUsage
    of(long promptTokens, long completionTokens)
    Convenience: minimal usage with only prompt + completion.
    long
    promptTokens()
    Returns the value of the promptTokens record component.
    long
    reasoningTokens()
    Returns the value of the reasoningTokens record component.
    final String
    toString()
    Returns a string representation of this record class.
    long
    totalTokens()
    Returns the value of the totalTokens record component.
    static TokenUsage
    zero()
    Convenience: zero usage — placeholder for failed calls.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • TokenUsage

      public TokenUsage(long promptTokens, long completionTokens, long cachedTokens, long reasoningTokens, long totalTokens)
      Creates an instance of a TokenUsage record class.
      Parameters:
      promptTokens - the value for the promptTokens record component
      completionTokens - the value for the completionTokens record component
      cachedTokens - the value for the cachedTokens record component
      reasoningTokens - the value for the reasoningTokens record component
      totalTokens - the value for the totalTokens record component

  • Method Details

    • of

      public static TokenUsage of(long promptTokens, long completionTokens)
      Convenience: minimal usage with only prompt + completion.

    • zero

      public static TokenUsage zero()
      Convenience: zero usage — placeholder for failed calls.

    • 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. All components in this record class 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.

    • promptTokens

      public long promptTokens()
      Returns the value of the promptTokens record component.
      Returns:
      the value of the promptTokens record component

    • completionTokens

      public long completionTokens()
      Returns the value of the completionTokens record component.
      Returns:
      the value of the completionTokens record component

    • cachedTokens

      public long cachedTokens()
      Returns the value of the cachedTokens record component.
      Returns:
      the value of the cachedTokens record component

    • reasoningTokens

      public long reasoningTokens()
      Returns the value of the reasoningTokens record component.
      Returns:
      the value of the reasoningTokens record component

    • totalTokens

      public long totalTokens()
      Returns the value of the totalTokens record component.
      Returns:
      the value of the totalTokens record component