Persistent Telemetry
Session tracking, cost analytics, and historical data with SQLite-backed persistence
Bootspring's telemetry system records every session, tool invocation, and cost metric to a local SQLite database. This gives you historical analytics, cost projection, and data export — all without sending data to any external service.
Overview
Telemetry captures three categories of data:
- Session lifecycle — Start, end, duration, task context
- Tool usage — Every MCP tool invocation with timing and token counts
- Cost tracking — Per-model token costs aggregated by session, day, and project
All data is stored locally in .bootspring/telemetry.db.
Database Schema
The telemetry database uses four tables.
sessions
| Column | Type | Description |
|---|---|---|
id | TEXT (PK) | Unique session identifier (UUID v4) |
project_id | TEXT | Project directory hash |
started_at | INTEGER | Unix timestamp (ms) |
ended_at | INTEGER | Unix timestamp (ms), null if active |
duration_ms | INTEGER | Computed duration |
task_id | TEXT | Associated build task (e.g., bs-1042) |
model | TEXT | Primary model used (e.g., claude-sonnet-4-20250514) |
status | TEXT | active, completed, abandoned |
events
| Column | Type | Description |
|---|---|---|
id | INTEGER (PK) | Auto-increment |
session_id | TEXT (FK) | References sessions.id |
type | TEXT | Event type (e.g., tool:invoke, command:run) |
name | TEXT | Tool or command name |
timestamp | INTEGER | Unix timestamp (ms) |
duration_ms | INTEGER | Execution time |
metadata | TEXT | JSON blob with event-specific data |
costs
| Column | Type | Description |
|---|---|---|
id | INTEGER (PK) | Auto-increment |
session_id | TEXT (FK) | References sessions.id |
model | TEXT | Model identifier |
input_tokens | INTEGER | Prompt tokens consumed |
output_tokens | INTEGER | Completion tokens generated |
cache_read_tokens | INTEGER | Tokens served from cache |
cost_usd | REAL | Computed cost in USD |
timestamp | INTEGER | Unix timestamp (ms) |
daily_aggregates
| Column | Type | Description |
|---|---|---|
date | TEXT (PK) | ISO date (YYYY-MM-DD) |
project_id | TEXT (PK) | Project directory hash |
sessions | INTEGER | Session count |
total_tokens | INTEGER | Sum of all tokens |
total_cost_usd | REAL | Sum of costs |
tools_invoked | INTEGER | Total tool invocations |
tasks_completed | INTEGER | Build tasks marked done |
Session Lifecycle
A session begins when any MCP tool is invoked or a CLI command runs. The lifecycle follows this flow:
[Tool invocation / CLI command]
│
▼
Session created (status: active)
│
├── Events recorded (tool calls, commands)
├── Costs accumulated (per-model tokens)
│
▼
Session ended (status: completed)
│
▼
Daily aggregates updated
Sessions end automatically after 30 minutes of inactivity or when bootspring session end is called explicitly. Abandoned sessions (process crash without clean shutdown) are cleaned up on next startup.
Cost Tracking
Costs are tracked per model using current token pricing:
| Model | Input (per 1M) | Output (per 1M) | Cache Read (per 1M) |
|---|---|---|---|
| claude-sonnet-4-20250514 | $3.00 | $15.00 | $0.30 |
| claude-opus-4-20250514 | $15.00 | $75.00 | $1.50 |
| claude-haiku-3-20250307 | $0.25 | $1.25 | $0.03 |
| gpt-4o | $2.50 | $10.00 | — |
| gpt-4o-mini | $0.15 | $0.60 | — |
View cost data from the CLI:
Historical Analytics
Query telemetry across three time windows.
7-Day View
Shows daily session count, token usage, cost trend, and top tools for the past week.
30-Day View
Adds weekly averages, cost projection for the remainder of the month, and tool usage distribution.
90-Day View
Adds monthly trends, learning curve analysis (are sessions getting more efficient?), and cost-per-task metrics.
Example Output
Data Export
Export telemetry data in CSV or JSON format.
CSV Format
The CSV export includes one row per session with flattened metrics:
session_id,started_at,ended_at,duration_ms,model,input_tokens,output_tokens,cost_usd,tools_invoked,task_id
a1b2c3,2026-04-10T09:00:00Z,2026-04-10T09:22:00Z,1320000,claude-sonnet-4-20250514,45200,12800,0.33,14,bs-1042
JSON Format
The JSON export includes the full event log per session:
Retention Policy
Telemetry data is retained locally according to these defaults:
| Data Type | Default Retention | Configurable |
|---|---|---|
| Raw events | 90 days | Yes |
| Session records | 1 year | Yes |
| Daily aggregates | Indefinite | Yes |
| Cost records | 1 year | Yes |
Configure retention in bootspring.config.js:
Run cleanup manually:
This removes records older than the configured retention period and runs VACUUM on the SQLite database.
Privacy Considerations
Telemetry is designed with privacy as a default:
- Local-only storage — All data stays in
.bootspring/telemetry.dbon your machine. Nothing is sent externally unless you explicitly export or upload. - No code content — Events record tool names and timing, never file contents or code snippets.
- No PII — Session data does not include usernames, emails, or identifiable information.
- Opt-out — Disable telemetry entirely with
BOOTSPRING_TELEMETRY=falseor in config. - Deletable — Run
bootspring telemetry clearto wipe all local telemetry data. - Gitignored —
.bootspring/telemetry.dbis excluded from version control by default.