Package com.tnsai.observability.events

Record Class EventContext

java.lang.Object
java.lang.Record
com.tnsai.observability.events.EventContext
public record EventContext(String tenantId, String sessionId, String traceId, String spanId, String agentId, String agentClass, String role, List<String> capabilities, Optional<String> groupId, Optional<String> conversationId, Map<String,String> extensions) extends Record
Correlation context attached to every observability event.

Carries the framework identity required to route a log line back to the agent / role / session / tenant that produced it. Populated automatically by framework entry points via AgentContext.enter(EventContext) and consumed by the AgentEventPublisher chain (and indirectly by SLF4J MDC, which is kept in sync).

Field semantics

  • tenantId — multi-tenant scope (e.g. "acme"). null/blank if not multi-tenant.
  • sessionId — user-interaction scope (one chat turn or the lifetime of a long-running session).
  • traceId / spanId — OTel correlation. Set by the trace provider; mirrored into MDC for log/trace correlation in vendors like Datadog, Honeycomb, Tempo.
  • agentId / agentClass — which agent instance produced the event and its concrete class.
  • role — active role at event time.
  • capabilities — capability ids active in this scope (used for capability-level error budgets in #92).
  • groupId — present iff the agent is running inside an AgentGroup.
  • conversationId — present for multi-turn conversations (orthogonal to sessionId; a session can span conversations).
  • extensions — operator-defined string→string fields (deployment, region, customer cohort, …). Kept low-cardinality.

All collection fields are defensively copied at construction; the record is structurally immutable so it is safe to share across threads. Builder pattern is provided to avoid the 11-positional-argument constructor at call sites.

Since:
0.5.0 (issue #78)

  • Constructor Details

    • EventContext

      public EventContext(String tenantId, String sessionId, String traceId, String spanId, String agentId, String agentClass, String role, List<String> capabilities, Optional<String> groupId, Optional<String> conversationId, Map<String,String> extensions)
      Creates an instance of a EventContext record class.
      Parameters:
      tenantId - the value for the tenantId record component
      sessionId - the value for the sessionId record component
      traceId - the value for the traceId record component
      spanId - the value for the spanId record component
      agentId - the value for the agentId record component
      agentClass - the value for the agentClass record component
      role - the value for the role record component
      capabilities - the value for the capabilities record component
      groupId - the value for the groupId record component
      conversationId - the value for the conversationId record component
      extensions - the value for the extensions record component

  • Method Details

    • empty

      public static EventContext empty()
      Empty context — used when no agent is active in the current thread.

    • builder

      public static EventContext.Builder builder()

    • withRole

      public EventContext withRole(String newRole)
      Returns a new context with the given field overridden. Used to compose nested scopes (outer agent → inner tool, outer session → inner action). All other fields are preserved.

    • withAgent

      public EventContext withAgent(String newAgentId, String newAgentClass)

    • withGroup

      public EventContext withGroup(String newGroupId)

    • 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 Objects::equals(Object,Object).
      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.

    • tenantId

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

    • sessionId

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

    • traceId

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

    • spanId

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

    • agentId

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

    • agentClass

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

    • role

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

    • capabilities

      public List<String> capabilities()
      Returns the value of the capabilities record component.
      Returns:
      the value of the capabilities record component

    • groupId

      public Optional<String> groupId()
      Returns the value of the groupId record component.
      Returns:
      the value of the groupId record component

    • conversationId

      public Optional<String> conversationId()
      Returns the value of the conversationId record component.
      Returns:
      the value of the conversationId record component

    • extensions

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