Telemetry Schema

​

Overview

discovery_runs ─┐
                │
                ▼
            sessions ── plans / step_results / guidance_notes
                │
                ├─ trajectory_events
                │
                └─ learning_registry

• discovery_runs captures onboarding metadata produced by atlas env init.
• sessions stores per-request telemetry, review status, reward stats, and learning notes.
• trajectory_events holds fine-grained telemetry (plan approvals, guidance, validations, tool calls).
• learning_registry caches the latest playbooks per learning_key.

​

discovery_runs

​

sessions

• sessions_reward_score_idx: Functional index on (reward_stats->>'score')::float for 10-100x faster reward filtering
• sessions_created_at_idx: Index on created_at DESC for 50-100x faster date range queries
• sessions_metadata_gin_idx: GIN index on metadata JSONB for learning key queries

​

Metadata Schema Fields (v0.1.13+)

• session_reward: Aggregate reward with score and uncertainty
• trajectory_events: Ordered list of runtime events
• student_learning: Student persona learning notes
• teacher_learning: Teacher persona learning notes
• learning_history: Historical learning data
• adaptive_summary: Mode selection (auto/paired/coach) and probe evidence

• learning_key: Task identifier for grouping sessions
• teacher_notes: Guidance provided during execution
• reward_summary: Simplified reward statistics
• drift: Detected schema or behavior drift
• drift_alert: Critical drift warnings requiring review
• triage_dossier: Pre-execution risk assessment
• reward_audit: Detailed judge breakdowns

​

Related tables

• plans – JSON plan snapshot keyed by session_id.
• step_results / step_attempts – per-step traces and validation payloads.
• guidance_notes – ordered teacher guidance emitted during execution.

​

step_results Schema Fields (v0.1.13+)

• runtime: Step execution time in milliseconds
• depends_on: Array of step IDs this step depends on (dependency graph)

• attempt_history: Previous attempt records if step was retried

-- Average step runtime by tool
SELECT
  metadata->>'tool' AS tool_name,
  AVG((metadata->>'runtime')::float) AS avg_runtime_ms
FROM step_results
WHERE metadata->>'runtime' IS NOT NULL
GROUP BY tool_name
ORDER BY avg_runtime_ms DESC;

​

trajectory_events

​

learning_registry

​

Query Examples

-- High-reward sessions for training (using performance index)
SELECT id, task, (reward_stats->>'score')::float AS reward
FROM sessions
WHERE (reward_stats->>'score')::float >= 0.8
  AND status = 'succeeded'
ORDER BY created_at DESC
LIMIT 1000;

-- Sessions awaiting review with drift alerts
SELECT id, task, metadata->'drift_alert' AS drift_alert
FROM sessions
WHERE review_status = 'pending'
  AND metadata ? 'drift_alert';

-- Latest playbooks for a service
SELECT learning_key, updated_at, student_learning
FROM learning_registry
WHERE learning_key LIKE 'service:%'
ORDER BY updated_at DESC;

-- Count validation events per session
SELECT session_id, COUNT(*) AS validation_events
FROM trajectory_events
WHERE event ->> 'event_type' = 'validation'
GROUP BY session_id;

-- Learning history for a task (using GIN index)
SELECT
  id,
  task,
  metadata->'learning_history' AS learning_history,
  (reward_stats->>'score')::float AS reward
FROM sessions
WHERE metadata @> '{"learning_key": "security-review"}'
ORDER BY created_at DESC;

-- Step performance analysis
SELECT
  s.task,
  sr.metadata->>'tool' AS tool,
  AVG((sr.metadata->>'runtime')::float) AS avg_runtime_ms,
  COUNT(*) AS step_count
FROM step_results sr
JOIN sessions s ON sr.session_id = s.id
WHERE sr.metadata->>'runtime' IS NOT NULL
GROUP BY s.task, sr.metadata->>'tool'
ORDER BY avg_runtime_ms DESC;

​

Related Pages

• Training Data Pipeline – Direct database access for training data extraction
• Export Runtime Traces – CLI usage and JSON schema for session exports
• Runtime Safety & Review – Review gating and drift detection
• Evaluation Harnesses – Harnesses that query the schema for analytics