Telemetry trust boundary and SSOT map
Purpose
This page is the normative documentation map for telemetry, observability, and trust boundaries in Vox. It complements:
- strategic research: Telemetry unification research findings 2026
- metric row rules: Telemetry and research_metrics contract
- implementation sequencing: Telemetry implementation blueprint 2026
- executable checklist: Telemetry implementation backlog 2026
- optional remote upload (explicit CLI only): ADR 023, Telemetry remote sink specification
Critique of the original research-only plan (folded)
The first telemetry-trust research pass was correct to defer code and schema changes. For implementation, the following gaps must stay explicit:
- Environment variable SSOT drift:
VOX_BENCHMARK_TELEMETRYandVOX_SYNTAX_K_TELEMETRYare implemented incrates/vox-cli/src/benchmark_telemetry.rsand must appear in Environment variables (SSOT) alongside deeper docs in orchestration-unified and mens-training. - Machine contracts beyond
research_metrics: context-lifecycle-telemetry.schema.json is part of the telemetry vocabulary; it is not optional detail. ci_completion_*is workspace-adjacent: Tables defined incrates/vox-db/src/schema/domains/ci_completion.rscarry paths and metadata. They are not interchangeable with coarse product telemetry without a separate sensitivity class (see Telemetry retention and sensitivity SSOT).- VS Code and debug surfaces: The extension webview uses a
telemetrytab id for local dashboards; that naming can collide with user expectations about “phone-home” telemetry. vscode-mcp-compat documentsvox.mcp.debugPayloads— high sensitivity and must sit inside the same trust framework as Ludus MCP arg modes. - Governance hooks: New operations and drift checks must stay aligned with operations catalog, data-ssot-guards, and CHANGELOG.
- Build timing telemetry: Shallow
vox ci build-timingsand deep--deeppaths write UsageTelemetry-class signals (coarse timings, crate names, dependency-shape summaries). Canonical structured rows live inbuild_run/build_crate_sample/build_warning/build_run_dependency_shape; summarizedbenchmark_eventrows useVOX_BENCHMARK_TELEMETRY(see telemetry-metric-contract “Build timing producers”). Query via MCPvox_benchmark_listwithsource=build_health|build_regressions|build_warnings|dependency_shape. Retention aligns with retention-policy.yaml and telemetry-retention-sensitivity-ssot.
Authoritative SSOT set (no duplicate primaries)
| Concern | Primary SSOT | Secondary / derivative |
|---|---|---|
research_metrics row shape, session prefixes, validation | telemetry-metric-contract, research_metrics_contract.rs | Crate doc comments |
| Env names and roles | env-vars | orchestration-unified, mens-training, populi SSOT |
| Table TTL hints for prune | retention-policy.yaml | db retention CLI |
| Completion CI telemetry schemas | contracts/telemetry/completion-*.v1.schema.json | completion-policy-ssot |
| Context lifecycle tracing fields | context-lifecycle-telemetry.schema.json | context_lifecycle.rs |
| Taxonomy and event families (rollout) | telemetry-taxonomy-contracts-ssot | contracts under contracts/telemetry/ |
| Client disclosure and debug | telemetry-client-disclosure-ssot | vox-vscode README |
Build timing + build_* observability | telemetry-metric-contract, crate-build-lanes-migration, ops_build.rs | vox ci build-timings; MCP vox_benchmark_list (source for build_*); CI may set VOX_BENCHMARK_TELEMETRY |
agent_exec_history timing | exec_time_telemetry.rs (S1) | agent_exec_time |
| Secrets for any future upload endpoint | AGENTS.md, Clavis | — |
Trust planes (normative vocabulary)
Use these terms consistently in docs and code comments:
| Plane | Meaning | Default posture |
|---|---|---|
| UsageTelemetry | Coarse, low-entropy signals for product improvement | Local-first; remote only with explicit opt-in (future) |
| Diagnostics | Support bundles, debug logs, user-reviewed export | Explicit action; never default remote |
| ContentPersistence | Chat, tool args, retrieval, transcripts | Local / operator store; not “telemetry” without separate consent story |
| OperationalTracing | Structured logs and local JSONL | Local; treat as sensitive if identifiers or content leak |
A2A dogfood JSONL: MCP may append optional a2a_traces.jsonl under a dogfood trace directory. That file is OperationalTracing-class convenience only; it is not interchangeable with Codex a2a_messages or mesh delivery logs.
Contributor rule
Any change that adds or widens data collection, persistence, or export must update:
- the relevant contract or SSOT doc,
- CHANGELOG,
- retention or sensitivity SSOT if TTL or class changes,
- operations catalog / CLI registry if a new operator-facing command or flag is introduced.
See doc-to-code acceptance checklist.