Package com.tnsai.quality.observability

Class AgentInstrumentation

java.lang.Object
com.tnsai.quality.observability.AgentInstrumentation
public class AgentInstrumentation extends Object
OpenTelemetry instrumentation for TnsAI agents.

This class provides tracing and metrics instrumentation for agent operations including chat, action execution, and tool calls. It uses a wrapper pattern to add observability without modifying the Agent class directly.

Usage Example


 // Initialize telemetry
 TnsAITelemetry telemetry = TnsAITelemetry.builder()
     .serviceName("my-agent-service")
     .build();

 // Create instrumentation
 AgentInstrumentation instrumentation = new AgentInstrumentation(telemetry);

 // Instrument agent operations
 Agent agent = new MyAgent(principal, scope); // passes a wired ActionExecutor, see com.tnsai.agents
 instrumentation.registerAgent(agent);

 // Operations are automatically traced
 String response = instrumentation.traceChat(agent, "Hello", () -> agent.chat("Hello"));

Traced Operations

  • agent.chat - Chat operations with user messages
  • agent.action - Action execution
  • agent.tool_call - Individual tool calls
  • agent.llm_call - LLM API calls

  • Constructor Details

    • AgentInstrumentation

      public AgentInstrumentation(TnsAITelemetry telemetry)
      Creates a new AgentInstrumentation with the given TnsAITelemetry.
      Parameters:
      telemetry - the TnsAITelemetry instance

    • AgentInstrumentation

      public AgentInstrumentation(OpenTelemetryTracer tracer, OpenTelemetryMetrics metrics)
      Creates a new AgentInstrumentation with custom tracer and metrics.
      Parameters:
      tracer - the OpenTelemetryTracer instance
      metrics - the OpenTelemetryMetrics instance

  • Method Details

    • registerAgent

      public void registerAgent(com.tnsai.agents.Agent agent)
      Registers an agent for instrumentation and increments active agent count.
      Parameters:
      agent - the agent to register

    • unregisterAgent

      public void unregisterAgent(com.tnsai.agents.Agent agent)
      Unregisters an agent and decrements active agent count.
      Parameters:
      agent - the agent to unregister

    • traceChat

      public <T> T traceChat(com.tnsai.agents.Agent agent, String message, Supplier<T> chatOperation)
      Traces a chat operation.
      Type Parameters:
      T - the return type
      Parameters:
      agent - the agent performing the chat
      message - the user message
      chatOperation - the chat operation to execute
      Returns:
      the result of the chat operation

    • traceAction

      public <T> T traceAction(com.tnsai.agents.Agent agent, String actionName, Map<String,Object> parameters, Supplier<T> actionOperation)
      Traces an action execution.
      Type Parameters:
      T - the return type
      Parameters:
      agent - the agent executing the action
      actionName - the name of the action
      parameters - the action parameters
      actionOperation - the action operation to execute
      Returns:
      the result of the action

    • traceToolCall

      public <T> T traceToolCall(com.tnsai.agents.Agent agent, String toolName, Map<String,Object> arguments, Supplier<T> toolOperation)
      Traces a tool call.
      Type Parameters:
      T - the return type
      Parameters:
      agent - the agent making the tool call
      toolName - the name of the tool
      arguments - the tool arguments
      toolOperation - the tool operation to execute
      Returns:
      the result of the tool call

    • traceLlmCall

      public <T> T traceLlmCall(com.tnsai.agents.Agent agent, String provider, String model, Supplier<T> llmOperation)
      Traces an LLM call with semantic conventions.
      Type Parameters:
      T - the return type
      Parameters:
      agent - the agent making the LLM call
      provider - the LLM provider name
      model - the model name
      llmOperation - the LLM operation to execute
      Returns:
      the result of the LLM call

    • recordLlmTokens

      public void recordLlmTokens(String provider, String model, long promptTokens, long completionTokens, double latencyMs)
      Records LLM token usage.
      Parameters:
      provider - the LLM provider
      model - the model name
      promptTokens - the number of prompt tokens
      completionTokens - the number of completion tokens
      latencyMs - the latency in milliseconds

    • recordLlmFailure

      public void recordLlmFailure(String provider, String model, double latencyMs, String errorType)
      Records a failed LLM call.
      Parameters:
      provider - the LLM provider
      model - the model name
      latencyMs - the latency in milliseconds
      errorType - the error type

    • getTracer

      public OpenTelemetryTracer getTracer()
      Gets the underlying OpenTelemetryTracer.

    • getMetrics

      public OpenTelemetryMetrics getMetrics()
      Gets the underlying OpenTelemetryMetrics.