You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat: add telemetry intelligence signals for debugging and improvements (#564)
* feat: add implicit quality signal telemetry event
Add `task_outcome_signal` event that maps agent outcomes to behavioral
signals (accepted/error/abandoned/cancelled). Emitted alongside
`agent_outcome` at session end with zero user cost — pure client-side
computation from data already in memory.
- New event type with `signal`, `tool_count`, `step_count`, `duration_ms`,
`last_tool_category` fields
- Exported `deriveQualitySignal()` for testable outcome→signal mapping
- MCP tool detection via `mcp__` prefix for accurate categorization
- 8 unit tests covering all signal derivations and event shape
Closes AI-6028
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add task intent classification telemetry event
Add `task_classified` event emitted at session start with keyword/regex
classification of the first user message. Categories: debug_dbt, write_sql,
optimize_query, build_model, analyze_lineage, explore_schema, migrate_sql,
manage_warehouse, finops, general.
- `classifyTaskIntent()` — pure regex matcher, zero LLM cost, <1ms
- Includes warehouse type from fingerprint cache
- Strong/weak confidence levels (1.0 vs 0.5)
- 15 unit tests covering all intent categories + edge cases
Closes AI-6029
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: emit aggregated tool chain outcome at session end
Add `tool_chain_outcome` event that captures the ordered tool sequence,
error count, recovery count, and final outcome at session end. Only
emitted when tools were actually used (non-empty chain).
- Tracks up to 50 tool names in execution order
- Detects error→success recovery patterns for auto-fix insights
- Aggregates existing per-tool-call data — near-zero additional cost
- 3 unit tests for event shape and error/recovery tracking
Closes AI-6030
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: link error-recovery pairs with hashed fingerprint
Add `error_fingerprint` event emitted per unique error at session end.
SHA256-hashes normalized error messages for anonymous grouping, links
each error to its recovery tool (if the next tool succeeded).
- `hashError()` — 16-char hex hash of masked error messages
- Tracks error→recovery pairs during tool chain execution
- Capped at 20 fingerprints per session to bound telemetry volume
- 4 unit tests for hashing, event shape, and recovery tracking
Closes AI-6031
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: emit SQL structure fingerprint using altimate-core
Add `sql_fingerprint` event emitted after successful SQL execution via
`sql_execute`. Uses `extractMetadata()` + `getStatementTypes()` from
altimate-core NAPI — local parsing, no API calls, ~1-5ms.
- Captures: statement types, categories, table/function count,
subqueries, aggregation, window functions, AST node count
- No table/column names or SQL content — PII-safe by design
- Wrapped in try/catch so fingerprinting never breaks query execution
- `computeSqlFingerprint()` exported from sql-classify for reuse
- 6 unit tests including PII safety verification
Closes AI-6032
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: expand environment_census with dbt project fingerprint
Add optional dbt project metrics to the existing `environment_census`
event: snapshot/seed count buckets, materialization distribution
(table/view/incremental/ephemeral counts). Data already parsed at
startup — just extracts more fields from the same manifest parse.
- Backward compatible — new fields are optional
- No extra file reads or API calls
Closes AI-6033
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: emit schema complexity signal during warehouse introspection
Add `schema_complexity` event emitted alongside `warehouse_introspection`
after successful schema indexing. Uses data already computed during
introspection — no extra warehouse queries.
- Bucketed table/column/schema counts + avg columns per table
- Division-by-zero guard for empty warehouses
- Emitted inside existing try/catch — never breaks introspection
Closes AI-6034
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: update telemetry reference with 7 new intelligence signals
Add task_outcome_signal, task_classified, tool_chain_outcome,
error_fingerprint, sql_fingerprint, schema_complexity to the event
catalog. Update environment_census description for new dbt fields.
Update naming convention section.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: add comprehensive integration tests for telemetry signals
Add 38 integration tests that verify all 7 telemetry signals fire
through real code paths with spy on Telemetry.track():
- Signal 1: quality signal derivation + error/abandoned/cancelled cases
- Signal 2: intent classifier with 10 real DE prompts + PII safety
- Signal 3: tool chain collection with error recovery state machine
- Signal 4: error fingerprint hashing + consecutive error flush
- Signal 5: SQL fingerprint via altimate-core (aggregation, CTE, DDL)
- Signal 6: environment_census expansion + backward compatibility
- Signal 7: schema complexity bucketing + zero-table edge case
- Full E2E: complete session simulation with all 7 signals in order
Also fixes regex patterns for natural language flexibility:
- dbt debug: allows words between "dbt" and error keywords
- migrate: allows words between "to/from" and warehouse name
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* test: add altimate-core failure isolation tests
Verify computeSqlFingerprint resilience when altimate-core NAPI:
- throws (segfault, OOM) — returns null, never leaks exception
- returns undefined — uses safe defaults (empty arrays, 0 counts)
- returns garbage data — handled gracefully via ?? fallbacks
Also verifies sql-execute.ts code structure ensures fingerprinting
runs AFTER query result and is wrapped in isolated try/catch.
Tests crash-resistant SQL inputs (control chars, empty, incomplete,
very wide queries) and deterministic output.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: address stakeholder review findings
Fixes from 5-stakeholder review (architect, privacy, perf, markers, tests):
- Marker fix: remove nested altimate_change start/end, fold new variables
into existing session telemetry tracking block
- Performance: cap errorRecords at 200 entries (prevent unbounded growth)
- Performance: slice intent classifier input to 2000 chars (bound regex)
- Architecture: fix import path in sql-execute.ts (../telemetry not ../../altimate/telemetry)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* chore: bump altimate-core to 0.2.6
Picks up extractMetadata fixes:
- Aggregate function names (COUNT, SUM, AVG, etc.) now in functions array
- IN (SELECT ...) and EXISTS (SELECT ...) subquery detection
- Any/All quantified comparison subquery detection (guarded)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|`error_recovered`| Successful recovery from a transient error (error type, strategy, attempt count) |
@@ -39,6 +39,12 @@ We collect the following categories of events:
39
39
|`sql_execute_failure`| A SQL execution fails (warehouse type, query type, error message, PII-masked SQL — no raw values) |
40
40
|`core_failure`| An internal tool error occurs (tool name, category, error class, truncated error message, PII-safe input signature, and optionally masked arguments — no raw values or credentials) |
41
41
|`first_launch`| Fired once on first CLI run after installation. Contains version and is_upgrade flag. No PII. |
42
+
|`task_outcome_signal`| Behavioral quality signal at session end — accepted, error, abandoned, or cancelled. Includes tool count, step count, duration, and last tool category. No user content. |
43
+
|`task_classified`| Intent classification of the first user message using keyword matching — category (e.g. `debug_dbt`, `write_sql`, `optimize_query`), confidence score, and detected warehouse type. No user text is sent — only the classified category. |
44
+
|`tool_chain_outcome`| Aggregated tool execution sequence at session end — ordered tool names (capped at 50), error count, recovery count, final outcome, duration, and cost. No tool arguments or outputs. |
45
+
|`error_fingerprint`| Hashed error pattern for anonymous grouping — SHA-256 hash of masked error message, error class, tool name, and whether recovery succeeded. Raw error content is never sent. |
46
+
|`sql_fingerprint`| SQL structural shape via AST parsing — statement types, table count, function count, subquery/aggregation/window function presence, and AST node count. No table names, column names, or SQL content. |
47
+
|`schema_complexity`| Warehouse schema structural metrics from introspection — bucketed table, column, and schema counts plus average columns per table. No schema names or content. |
42
48
43
49
Each event includes a timestamp, anonymous session ID, CLI version, and an anonymous machine ID (a random UUID stored in `~/.altimate/machine-id`, generated once and never tied to any personal information).
44
50
@@ -129,6 +135,11 @@ Event type names use **snake_case** with a `domain_action` pattern:
129
135
-`context_utilization`, `context_overflow_recovered` for context management events
130
136
-`agent_outcome` for agent session events
131
137
-`error_recovered` for error recovery events
138
+
-`task_outcome_signal`, `task_classified` for session quality signals
139
+
-`tool_chain_outcome` for tool execution chain aggregation
140
+
-`error_fingerprint` for anonymous error pattern grouping
0 commit comments