Package com.tnsai.quality.observability

package com.tnsai.quality.observability
Observability and telemetry integration using OpenTelemetry.

This package provides instrumentation for monitoring agent behavior, performance, and debugging through distributed tracing and metrics.

OpenTelemetry Integration

 ┌─────────────────────────────────────────────────────────────┐
 │                    Observability Stack                       │
 ├─────────────────────────────────────────────────────────────┤
 │                                                              │
 │  Agent ──► Tracer ──► Spans ──► OTLP Exporter              │
 │                                        │                     │
 │                                        ▼                     │
 │                              ┌─────────────────┐            │
 │                              │  Jaeger/Zipkin  │            │
 │                              │  Grafana/etc.   │            │
 │                              └─────────────────┘            │
 │                                                              │
 └─────────────────────────────────────────────────────────────┘

Traced Operations

OperationSpan NameAttributes
Agent runagent.runagent.name, input.length
LLM callllm.chatmodel, tokens.input, tokens.output
Tool calltool.executetool.name, duration
Memory opsmemory.save/loadmessage.count

Usage Example


 // Enable observability (auto-configured via OpenTelemetry SDK)
 // Set environment variables:
 // OTEL_SERVICE_NAME=my-agent-app
 // OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

 // Traces are automatically created for:
 Agent agent = new MyAgent(principal, scope); // passes a wired ActionExecutor, see com.tnsai.agents
 String response = agent.run("Hello"); // Creates agent.run span

 // Custom spans
 Tracer tracer = GlobalOpenTelemetry.getTracer("my-component");
 Span span = tracer.spanBuilder("custom-operation").startSpan();
 try (Scope scope = span.makeCurrent()) {
     // Your code here
 } finally {
     span.end();
 }

Semantic Conventions

Follows OpenTelemetry semantic conventions for:

  • General AI/ML spans
  • HTTP client spans (for LLM API calls)
  • Database spans (for memory operations)

Configuration

Specure via environment variables or programmatically:

  • OTEL_SERVICE_NAME: Service identifier
  • OTEL_EXPORTER_OTLP_ENDPOINT: Collector endpoint
  • OTEL_TRACES_SAMPLER: Sampling strategy
See Also:
  • Tracer
  • Span