Package com.tnsai.quality.observability

Class AgentLogger

java.lang.Object
com.tnsai.quality.observability.AgentLogger
public final class AgentLogger extends Object
Structured logger for agent operations with automatic trace context propagation.

AgentLogger wraps SLF4J and adds:

  • Automatic trace context in MDC
  • Structured logging support with key-value pairs
  • Agent-specific context (agent ID, role, action)
  • Operation timing and metrics

Example usage: 

 AgentLogger logger = AgentLogger.forAgent("my-agent");

 // Simple logging with context
 logger.info("Processing request")
       .with("userId", "123")
       .with("action", "search")
       .log();

 // With trace context
 logger.withTrace(traceContext)
       .info("Action completed")
       .with("result", "success")
       .with("durationMs", 150)
       .log();

 // Timed operation
 Object result = logger.timed("database-query", () -> {
     return db.query("SELECT ...");
 });

 // Error logging
 logger.error("Operation failed", exception)
       .with("action", "processPayment")
       .log();
See Also:

  • Method Details

    • forAgent

      public static AgentLogger forAgent(String agentId)
      Creates a logger for an agent.
      Parameters:
      agentId - the agent identifier
      Returns:
      a new agent logger

    • forAgent

      public static AgentLogger forAgent(String agentId, Class<?> loggerClass)
      Creates a logger for an agent with a custom logger class.
      Parameters:
      agentId - the agent identifier
      loggerClass - the class for logger naming
      Returns:
      a new agent logger

    • withTrace

      public AgentLogger withTrace(TraceContext trace)
      Sets the trace context for subsequent log calls.
      Parameters:
      trace - the trace context
      Returns:
      this logger for chaining

    • withCurrentTrace

      public AgentLogger withCurrentTrace()
      Uses the current thread's trace context.
      Returns:
      this logger for chaining

    • debug

      public AgentLogger.LogEntry debug(String message)
      Creates a debug log entry.
      Parameters:
      message - the log message
      Returns:
      a log entry builder

    • info

      public AgentLogger.LogEntry info(String message)
      Creates an info log entry.
      Parameters:
      message - the log message
      Returns:
      a log entry builder

    • warn

      public AgentLogger.LogEntry warn(String message)
      Creates a warn log entry.
      Parameters:
      message - the log message
      Returns:
      a log entry builder

    • warn

      public AgentLogger.LogEntry warn(String message, Throwable throwable)
      Creates a warn log entry with exception.
      Parameters:
      message - the log message
      throwable - the exception
      Returns:
      a log entry builder

    • error

      public AgentLogger.LogEntry error(String message)
      Creates an error log entry.
      Parameters:
      message - the log message
      Returns:
      a log entry builder

    • error

      public AgentLogger.LogEntry error(String message, Throwable throwable)
      Creates an error log entry with exception.
      Parameters:
      message - the log message
      throwable - the exception
      Returns:
      a log entry builder

    • logActionStart

      public void logActionStart(String actionName, Map<String,Object> parameters)
      Logs action start.
      Parameters:
      actionName - the action name
      parameters - the action parameters

    • logActionComplete

      public void logActionComplete(String actionName, long durationMs, boolean success)
      Logs action completion.
      Parameters:
      actionName - the action name
      durationMs - the duration in milliseconds
      success - whether the action succeeded

    • logActionError

      public void logActionError(String actionName, Throwable exception)
      Logs action failure.
      Parameters:
      actionName - the action name
      exception - the exception

    • logLLMCall

      public void logLLMCall(String model, int promptTokens, long durationMs)
      Logs LLM call.
      Parameters:
      model - the model name
      promptTokens - estimated prompt tokens
      durationMs - call duration

    • timed

      public <T> T timed(String operationName, Supplier<T> operation)
      Executes and times an operation.
      Type Parameters:
      T - the return type
      Parameters:
      operationName - the operation name
      operation - the operation to execute
      Returns:
      the operation result

    • timedRun

      public void timedRun(String operationName, Runnable operation)
      Executes and times a void operation.
      Parameters:
      operationName - the operation name
      operation - the operation to execute