Observability

// Structured logging
AgentLogger logger = AgentLogger.forAgent("agent-001");
logger.info("Processing request")
    .with("userId", userId)
    .with("action", "search")
    .log();

TnsAITelemetry telemetry = TnsAITelemetry.builder()
    .serviceName("my-agent-service")
    .serviceVersion("1.0.0")
    .otlpEndpoint("http://localhost:4317")
    .build();

OpenTelemetryTracer tracer = new OpenTelemetryTracer(telemetry.getTracer());

try (SpanScope scope = tracer.startSpan("process-request")) {
    scope.setAttribute("user.id", userId);
    scope.setAttribute("request.type", "search");
    // ... work happens here ...
    scope.setSuccess();
} // Span automatically closed

// Convenience wrapper
String result = tracer.trace("fetch-data", () -> fetchData(query));

OpenTelemetryMetrics metrics = new OpenTelemetryMetrics(meter);

// Record agent actions
metrics.recordActionSuccess("search", 150);  // type, duration ms
metrics.recordActionFailure("write", 50, "timeout");

// Record LLM calls
metrics.recordLlmCall("openai", "gpt-4o", 1000, 500, 2300);  // provider, model, tokens, latency
metrics.recordLlmCallFailure("anthropic", "claude-3", 1500, "rate_limit");

// Gauges
metrics.setActiveAgents(5);

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

// Fluent API
logger.info("Tool executed")
    .with("tool", "brave_search")
    .with("duration", 350)
    .log();

// Convenience methods
logger.logActionStart("searchPapers", params);
logger.logActionComplete("searchPapers", 1200, true);
logger.logLLMCall("gpt-4o", 500, 2100);

// Timed execution
String result = logger.timed("database-query", () -> db.query(sql));

// Create with theme
ThemedLogger logger = ThemedLogger.create("my-agent", LogThemes.STAR_WARS);

// Log events — each gets a themed prefix
logger.actionStart("Searching for documents");
// Output: [LIGHTSABER ON] Searching for documents

logger.actionComplete("Found 5 documents");
// Output: [THE FORCE SUCCEEDS] Found 5 documents

logger.error("Connection failed");
// Output: [SITH LORD DETECTED] Connection failed

// Startup/shutdown banners
logger.logStartup();
// Output: A long time ago in a galaxy far, far away... TnsAI awakens.

// With explicit theme
ThemedLogger logger = ThemedLogger.create("agent-001", LogThemes.LOTR);

// Default theme (no prefix)
ThemedLogger logger = ThemedLogger.create("agent-001");

// From class name
ThemedLogger logger = ThemedLogger.forClass(MyAgent.class, LogThemes.MATRIX);

// Implement LogTheme interface
LogTheme custom = new LogTheme() {
    public String name() { return "custom"; }
    public String format(LogEvent event, String message) {
        return "[MY-PREFIX] " + message;
    }
};

// Register for lookup by name
LogThemes.register(custom);
LogTheme theme = LogThemes.get("custom");

// Change theme at runtime
logger.setTheme(LogThemes.PIRATE);

// List and check themes
String[] names = LogThemes.listThemes();
boolean exists = LogThemes.hasTheme("starwars");

// Create and start
PrometheusMetricsExporter exporter = PrometheusMetricsExporter.builder()
    .port(9090)
    .build();
exporter.start();
// Metrics available at http://localhost:9090/metrics

// Record metrics
exporter.recordActionSuccess("search", 150);       // type, duration ms
exporter.recordActionFailure("write", "timeout", 50);
exporter.recordLlmCall("openai", "gpt-4o", 1000, 500, 2300);
exporter.recordLlmCallFailure("anthropic", "claude-3", "rate_limit", 1500);
exporter.setActiveAgents(5);

// One-liner startup
PrometheusMetricsExporter exporter = PrometheusMetricsExporter.createAndStart();

// Shutdown
exporter.stop();

// Configure from environment
PrometheusMetricsExporter exporter = PrometheusMetricsExporter.builder()
    .fromEnvironment()
    .build();

Counter counter = exporter.getOrCreateCounter("my_counter", "My help text", "label1");
Gauge gauge = exporter.getOrCreateGauge("my_gauge", "My help text", "label1");
Histogram histogram = exporter.getOrCreateHistogram("my_histogram", "My help text", "label1");

LlmInstrumentation llmInstr = new LlmInstrumentation(telemetry.getTracer());

// Trace a chat completion
ChatResponse response = llmInstr.traceChat("openai", "gpt-4", () -> {
    return client.chat(message);
});

// With request parameters
ChatResponse response = llmInstr.traceChat("openai", "gpt-4", 4096, 0.7, () -> {
    return client.chat(message);
});

// Trace streaming
Stream<ChatChunk> stream = llmInstr.traceStreamChat("anthropic", "claude-3", () -> {
    return client.streamChat(message);
});

// Trace embeddings
List<float[]> embeddings = llmInstr.traceEmbeddings("openai", "text-embedding-3", 10, () -> {
    return client.embed(inputs);
});

Span span = Span.current();
llmInstr.recordTokenUsage(span, 150, 50);
llmInstr.recordResponse(span, 150, 50, "stop");
llmInstr.recordToolUse(span, 3);
llmInstr.recordToolCallEvent(span, "brave_search", true);

Span span = llmInstr.spanBuilder("openai", "gpt-4")
    .operation("chat")
    .maxTokens(4096)
    .temperature(0.7)
    .topP(0.9)
    .agent("agent-001", "ResearchAgent")
    .messageLength(500)
    .toolUseEnabled(true)
    .start();

// Initialize
AgentInstrumentation instrumentation = new AgentInstrumentation(telemetry);
// Or with custom tracer/metrics
AgentInstrumentation instrumentation = new AgentInstrumentation(tracer, metrics);

// Register agents (increments active agent gauge)
instrumentation.registerAgent(agent);

// Trace chat
String response = instrumentation.traceChat(agent, "Hello", () -> {
    return agent.chat("Hello");
});

// Trace action execution
Object result = instrumentation.traceAction(agent, "searchPapers", params, () -> {
    return agent.executeAction("searchPapers", params);
});

// Trace tool call
String output = instrumentation.traceToolCall(agent, "brave_search", args, () -> {
    return tool.execute(args);
});

// Trace LLM call with GenAI conventions
ChatResponse resp = instrumentation.traceLlmCall(agent, "openai", "gpt-4", () -> {
    return llmClient.chat(messages);
});

instrumentation.recordLlmTokens("openai", "gpt-4", 150, 50, 2300);
instrumentation.recordLlmFailure("openai", "gpt-4", 1500, "rate_limit");
instrumentation.unregisterAgent(agent);  // decrements active agent gauge

AgentTrace trace = AgentTrace.start("agent-001", "research-task");

// Add observations during execution
trace.addObservation(Observation.span("llm-call")
    .input("Summarize the document")
    .output("The document describes...")
    .duration(Duration.ofMillis(2300))
    .metadata(Map.of("model", "claude-sonnet-4", "tokens", 1500))
    .build());

trace.addObservation(Observation.generation("tool-call")
    .input(Map.of("tool", "brave_search", "query", "quantum computing"))
    .output("Results: ...")
    .build());

trace.addObservation(Observation.event("guardrail-check")
    .metadata(Map.of("guardrail", "pii-filter", "passed", true))
    .build());

trace.complete();

// Numeric score
trace.addScore(Score.numeric("relevance", 0.92));

// Boolean score
trace.addScore(Score.bool("contains_pii", false));

// Categorical score
trace.addScore(Score.categorical("sentiment", "positive"));

// Set current trace for this thread
TraceContext.set(trace);

// Get current trace (returns Optional)
AgentTrace current = TraceContext.current().orElseThrow();

// Nested spans auto-link to parent
try (var scope = TraceContext.startSpan("sub-operation")) {
    // This span's parentId is automatically set to the enclosing span
    doWork();
}

// Clear when done
TraceContext.clear();

public interface Guardrail {
    GuardrailResult evaluate(AgentTrace trace);
    String name();
}

PiiGuardrail piiGuard = new PiiGuardrail();
GuardrailResult result = piiGuard.evaluate(trace);

if (!result.passed()) {
    System.out.println("PII detected: " + result.findings());
    // Findings include: type (EMAIL, PHONE, SSN, etc.), location, severity
}

Agent agent = AgentBuilder.create()
    .model("claude-sonnet-4")
    .guardrail(new PiiGuardrail())
    .build();

HealthCheckResult.up()                        // healthy
HealthCheckResult.up("All good")              // healthy with message
HealthCheckResult.down()                      // unhealthy
HealthCheckResult.down("Connection refused")  // unhealthy with message
HealthCheckResult.down(exception)             // unhealthy from exception
HealthCheckResult.degraded("High latency")    // degraded
HealthCheckResult.unknown("Check timed out")  // unknown
HealthCheckResult.of(status, message)         // any status

// Add details (immutable — returns new instance)
HealthCheckResult result = HealthCheckResult.up()
    .withDetail("connections", 10)
    .withDetail("latency_ms", 50)
    .withDuration(duration);

// Inspect
result.getStatus();         // HealthStatus enum
result.getMessage();        // String or null
result.getDetails();        // Map<String, Object>
result.isHealthy();         // true if UP or DEGRADED
result.getDuration();       // Duration or null
result.toMap();             // Map for JSON serialization
result.combine(other);      // returns result with worse status

// Implement for custom components
public class DatabaseHealth implements HealthIndicator {
    public String getName() { return "database"; }
    public HealthCheckResult check() {
        return conn.isValid(5) ? HealthCheckResult.up() : HealthCheckResult.down();
    }
}

// Lambda shorthand — from boolean
HealthIndicator simple = HealthIndicator.of("cache", () -> cache.isConnected());

// Lambda shorthand — from supplier
HealthIndicator detailed = HealthIndicator.of("cache", () -> {
    return HealthCheckResult.up().withDetail("size", cache.size());
});

// Async and timeout support (default methods)
CompletableFuture<HealthCheckResult> future = indicator.checkAsync();
HealthCheckResult result = indicator.checkWithTimeout(Duration.ofSeconds(2));

HealthRegistry registry = HealthRegistry.getInstance();  // singleton

// Register indicators
registry.register(new ResourceHealthIndicator());
registry.register("custom", HealthIndicator.of("custom", () -> true));

// Check health
Optional<HealthCheckResult> single = registry.check("database");
HealthCheckResult all = registry.checkAll();                          // default 30s timeout
HealthCheckResult all = registry.checkAll(Duration.ofSeconds(10));    // custom timeout
CompletableFuture<HealthCheckResult> async = registry.checkAllAsync();
HealthCheckResult matched = registry.checkMatching("db-*");           // wildcard

// Quick status (2s timeout per indicator)
HealthStatus status = registry.getQuickStatus();  // UP, DOWN, DEGRADED, or UNKNOWN

// HTTP-ready summary
Map<String, Object> summary = registry.getHealthSummary();
// { "status": "UP", "timestamp": "...", "totalDurationMs": 45,
//   "components": { "database": {...}, "cache": {...} } }

// Management
registry.getIndicatorNames();  // Set<String>
registry.getIndicatorCount();  // int
registry.unregister("old");
registry.clear();
registry.shutdown();           // call on app shutdown

// Default thresholds (85% memory, 90% CPU)
registry.register(new ResourceHealthIndicator());

// Custom thresholds
registry.register(new ResourceHealthIndicator(0.9, 0.9));

// Direct queries
ResourceHealthIndicator res = new ResourceHealthIndicator();
double heapUsage = res.getHeapUsageRatio();   // 0.0-1.0
int threads = res.getThreadCount();
boolean deadlock = res.hasDeadlock();