Core Concepts: Logs

What are Logs?

Logs are automatic records of every AI request and response. Each log captures the full interaction: what was sent, what was received, how long it took, and whether caching was used.

What's in a Log

Essential Data:

Request: endpoint, method, function_name, full request body
Response: status code, response body (truncated if > 100KB), duration in ms
Model: AI provider and model used (e.g., openai/gpt-4)
Agent & Skill: Which agent and skill configuration handled it

Caching:

cache_status: HIT, SEMANTIC_HIT, MISS, SEMANTIC_MISS, REFRESH, or DISABLED
Helps you see how often cache is saving costs

Hooks:

hook_logs: Array of all hook executions with timing and results
Each hook shows its own cache_status and duration

Embeddings (Optional):

1536-dimensional vectors created for chat/completion requests
Used to automatically cluster similar requests
Generated from conversation messages using text-embedding-3-small

Tracing (Optional):

trace_id, span_id, parent_span_id for distributed tracing
User metadata: app_id, external_user_id, custom fields

Querying Logs

API: GET /v1/reactive-agents/observability/logs

Common filters:

agent_id, skill_id - filter by agent or skill
before, after - time range queries
status - filter by HTTP status code
cache_status - see only hits or misses
embedding_not_null - logs with embeddings for clustering
limit, offset - pagination

What Happens After Logging

Real-time Broadcast: Logs instantly stream to connected UI clients
Database Storage: Persisted to PostgreSQL with indexes on agent_id, skill_id, timestamps
Evaluation Trigger-: Successful requests get scored by evaluations which teaches Reactive Agents which configurations work better
Grouping: Embeddings feed into auto-grouping to group similar requests

Why Logs Matter

Debugging: See exact requests/responses when something breaks
Optimization: Logs with embeddings enable automatic skill clustering
Performance: Track duration and identify slow requests
Caching: Measure cache effectiveness to reduce costs
Evaluation: Every log can trigger evaluations that improve your configurations