Docs/Core Concepts/Observability Observability Model
ANTS Platform provides comprehensive observability for AI agents through traces, metrics, logs, and metadata.
What is Observability?
Observability is the ability to understand the internal state of a system by examining its external outputs. For AI systems, this means:
- Understanding what your agents are doing
- Diagnosing why they behave certain ways
- Optimizing performance and costs
- Ensuring quality and compliance
The Three Pillars of Observability
1. Traces
Traces show the complete execution path of a request:
2. Metrics
Metrics are quantitative measurements over time:
// Performance metrics
latency: {
p50: 1200ms,
p95: 3500ms,
p99: 5200ms
}
// Volume metrics
throughput: 45 requests/second
total_requests: 1,234,567
// Quality metrics
error_rate: 0.5%
success_rate: 99.5%
// Cost metrics
total_tokens: 125M
cost_per_request: $0.023
3. Logs
Logs capture discrete events:
[2025-10-23 14:23:45] INFO Agent started: customer-support-agent
[2025-10-23 14:23:45] DEBUG Input received: "Help with my order"
[2025-10-23 14:23:46] INFO Context retrieved: 3 documents
[2025-10-23 14:23:47] DEBUG LLM tokens: prompt=150, completion=200
[2025-10-23 14:23:48] INFO Response sent successfully
[2025-10-23 14:23:48] METRIC Duration: 2.5s, Cost: $0.0105
Hierarchy
Entities
Organization
Your company or team:
{
id: 'org_abc123',
name: 'Acme Corp',
plan: 'enterprise',
credits: 50000
}
Project
A logical grouping of agents:
{
id: 'proj_xyz789',
name: 'Customer Support',
organization: 'org_abc123',
environments: ['production', 'staging', 'development']
}
Environment
Deployment environment:
{
id: 'env_prod',
name: 'production',
project: 'proj_xyz789'
}
Agent
An AI agent or system:
{
id: 'agent_support',
name: 'customer-support-agent',
version: '1.2.3',
framework: 'langchain',
model: 'gpt-4'
}
Trace
Complete execution of a request:
{
id: 'trace_abc123',
name: 'customer-support-query',
startTime: '2025-10-23T14:23:45Z',
endTime: '2025-10-23T14:23:48Z',
duration: 2500, // ms
status: 'success',
input: 'Help with my order',
output: 'I can help you track your order...',
metadata: {
userId: 'user_123',
sessionId: 'session_abc',
channel: 'web'
},
spans: [...],
tokens: 350,
cost: 0.0105
}
Span
Single unit of work within a trace:
{
id: 'span_xyz',
traceId: 'trace_abc123',
parentId: null, // or parent span ID
name: 'llm-inference',
startTime: '2025-10-23T14:23:46Z',
endTime: '2025-10-23T14:23:48Z',
duration: 2000, // ms
attributes: {
model: 'gpt-4',
temperature: 0.7,
maxTokens: 500
},
events: [...],
status: 'ok'
}
Event
Point-in-time occurrence:
{
id: 'event_123',
spanId: 'span_xyz',
timestamp: '2025-10-23T14:23:47Z',
name: 'token_usage',
attributes: {
promptTokens: 150,
completionTokens: 200,
totalTokens: 350
}
}
Collection Methods
SDK Instrumentation
Most common method - use our SDKs. Set up tracing once at startup (e.g. in an instrumentation.ts imported first), then wrap your code:
// instrumentation.ts — imported before anything else
const provider = new NodeTracerProvider({
spanProcessors: [
new AntsPlatformSpanProcessor({
publicKey: process.env.ANTS_PLATFORM_PUBLIC_KEY,
secretKey: process.env.ANTS_PLATFORM_SECRET_KEY,
baseUrl: 'https://api.antsplatform.ai'
})
]
})
provider.register()
setAntsPlatformTracerProvider(provider)
// Wrap a function so every call is traced
const handleQuery = observe(
async (userQuery: string) => myAgent.process(userQuery),
{ name: 'my-agent' }
)
const result = await handleQuery(userQuery)
// Or instrument manually with a span you end yourself
const span = startObservation('span', { name: 'my-agent' })
const output = await myAgent.process(userQuery)
span.end()
Auto-Instrumentation
Automatic instrumentation for supported frameworks. For LangChain, pass our callback handler; every call is then traced:
from ants_platform import AntsPlatform
from ants_platform.langchain import CallbackHandler
from langchain_openai import ChatOpenAI
# Configure the client once (reads keys from env or pass explicitly)
AntsPlatform(
public_key=os.getenv("ANTS_PLATFORM_PUBLIC_KEY"),
secret_key=os.getenv("ANTS_PLATFORM_SECRET_KEY"),
host="https://api.antsplatform.ai",
)
handler = CallbackHandler()
llm = ChatOpenAI()
result = llm.invoke("What is AI?", config={"callbacks": [handler]}) # Automatically traced
The same works for the OpenAI SDK as a drop-in replacement — swap the import and every call is traced:
# Replace `import openai` with the line below; nothing else changes
from ants_platform.openai import openai
response = openai.chat.completions.create(
model="gpt-4",
messages=[{"role": "user", "content": "What is AI?"}],
)
OpenTelemetry
Standards-based instrumentation via OpenTelemetry (requires Node.js 20+):
const provider = new NodeTracerProvider({
spanProcessors: [
new AntsPlatformSpanProcessor({
publicKey: process.env.ANTS_PLATFORM_PUBLIC_KEY,
secretKey: process.env.ANTS_PLATFORM_SECRET_KEY,
baseUrl: 'https://api.antsplatform.ai'
})
]
})
provider.register()
setAntsPlatformTracerProvider(provider)
// In short-lived scripts, flush before exit:
await provider.forceFlush()
Querying Data
Dashboard UI
Visual exploration of data:
- Live Dashboard: Real-time metrics and traces
- Trace Explorer: Search and filter traces
- Metrics Dashboard: Time-series visualizations
- Agent Analytics: Per-agent insights
REST API
The SDK's REST client (AntsPlatformClient) provides programmatic access to prompts, datasets, and scores using a public/secret key pair. Traces are captured through the tracing setup shown above, not written through this client.
const client = new AntsPlatformClient({
publicKey: process.env.ANTS_PLATFORM_PUBLIC_KEY,
secretKey: process.env.ANTS_PLATFORM_SECRET_KEY,
baseUrl: 'https://api.antsplatform.ai'
})
Querying Traces and Metrics
Searching, filtering, and aggregating traces, metrics, and trends are dashboard features. Explore and query your data in the ANTS Platform dashboard — there is no programmatic trace-query or metrics-aggregation API in the SDK.
Visualization
Real-Time Dashboards
Monitor live metrics, build custom dashboards (time-series, gauges, histograms), and configure alerts in the ANTS Platform dashboard. Dashboards and alerting are dashboard features and are not configured through the SDK.
Trace Visualization
Flamegraphs and waterfalls:
Data Retention
Retention Policies
Retention for traces, aggregated metrics, and logs is configured per project in the ANTS Platform dashboard. A typical tiered policy keeps raw traces in hot storage for 7 days, warm for 30 days, and cold for 90 days, with coarser-resolution metrics retained for up to a year. This is managed from the dashboard, not the SDK.
Data Lifecycle
New Data → Hot Storage (7 days, fast queries)
↓
Warm Storage (30 days, normal queries)
↓
Cold Storage (90 days, slower queries)
↓
Deleted (configurable)
Best Practices
1. Rich Context
Include relevant metadata on the active trace:
await startActiveObservation('span', { name: 'agent-execution' }, async () => {
updateActiveTrace({
metadata: {
// User context
userId: 'user_123',
sessionId: 'session_abc',
// Business context
customerId: 'customer_456',
accountType: 'enterprise',
// Technical context
agentVersion: '1.2.3',
model: 'gpt-4',
region: 'us-east-1'
}
})
return myAgent.process(query)
})
2. Consistent Naming
Use clear, hierarchical names:
Good:
customer-support.classify-intent
customer-support.retrieve-context
customer-support.generate-response
Avoid:
func1
process
handler
3. Error Tracking
Always capture errors with context:
from ants_platform import get_client
client = get_client()
with client.start_as_current_span(name="agent-execution") as span:
try:
result = agent.process(query)
client.update_current_span(output=result)
except Exception as error:
client.update_current_span(
level="ERROR",
status_message=str(error),
metadata={
"stack": traceback.format_exc(),
"query": query,
"agent_state": agent.get_state(),
},
)
raise
4. Sampling Strategy
Sample intelligently to control costs:
// Always sample errors and slow requests
// Sample 10% of normal requests
const shouldTrace = (request) => {
if (request.error) return true
if (request.duration > 5000) return true
return Math.random() < 0.1
}
Next Steps