Skip to content

vox-telemetry API Reference (generated)

Crate: vox-telemetry · Version: 0.6.0 · Target: Library (lib.rs)

L1 telemetry facade: canonical metric-type constants, TelemetryRecorder trait, and record_event! macro. Zero domain dependencies.

vox-telemetry — L1 telemetry facade.

Zero domain dependencies. Every emitter in the workspace depends on this crate for the record_event! macro and METRIC_TYPE_* constants. Sinks live in higher-layer crates (vox-db, vox-cli) and register themselves at binary startup via [set_global_recorder].

use vox_telemetry::{record_event, TelemetryEvent, ResearchMetricEvent, METRIC_TYPE_BENCHMARK_EVENT};
record_event!(&TelemetryEvent::ResearchMetric(ResearchMetricEvent {
session_id: "bench:myrepo".into(),
metric_type: METRIC_TYPE_BENCHMARK_EVENT.into(),
metric_value: Some(42.0),
metadata_json: None,
}));

If no recorder is registered, record_event! is a no-op.

ModuleDescription
aggregator—
config—
no_op—
recorder—
research_trial—
semcov_wave27_tests—
span—
types—
Dependency Topology, diagram 113 nodes, 12 edges: vox-actor-runtime → vox-telemetry; vox-audit → vox-telemetry; vox-cli → vox-telemetry; vox-cli-ci → vox-telemetry; vox-cli-research → vox-telemetry; vox-code-audit → vox-telemetry; vox-compiler → vox-telemetry; vox-config → vox-telemetry; vox-db → vox-telemetry; vox-effort-audit…vox-telemetryvox-actor-runtimevox-auditvox-clivox-cli-civox-cli-researchvox-code-auditvox-compilervox-configvox-dbvox-effort-auditvox-effort-routevox-orchestrator
Diagram source
graph {
direction: right
node vox_telemetry: "vox-telemetry"
node vox_actor_runtime: "vox-actor-runtime"
vox_actor_runtime -> vox_telemetry
node vox_audit: "vox-audit"
vox_audit -> vox_telemetry
node vox_cli: "vox-cli"
vox_cli -> vox_telemetry
node vox_cli_ci: "vox-cli-ci"
vox_cli_ci -> vox_telemetry
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_telemetry
node vox_code_audit: "vox-code-audit"
vox_code_audit -> vox_telemetry
node vox_compiler: "vox-compiler"
vox_compiler -> vox_telemetry
node vox_config: "vox-config"
vox_config -> vox_telemetry
node vox_db: "vox-db"
vox_db -> vox_telemetry
node vox_effort_audit: "vox-effort-audit"
vox_effort_audit -> vox_telemetry
node vox_effort_route: "vox-effort-route"
vox_effort_route -> vox_telemetry
node vox_orchestrator: "vox-orchestrator"
vox_orchestrator -> vox_telemetry
}
Consumer CrateRole
vox-actor-runtimeDirect workspace dependent
vox-auditDirect workspace dependent
vox-cliDirect workspace dependent
vox-cli-ciDirect workspace dependent
vox-cli-researchDirect workspace dependent
vox-code-auditDirect workspace dependent
vox-compilerDirect workspace dependent
vox-configDirect workspace dependent
vox-dbDirect workspace dependent
vox-effort-auditDirect workspace dependent
vox-effort-routeDirect workspace dependent
vox-orchestratorDirect workspace dependent
vox-orchestrator-mcpDirect workspace dependent
vox-orchestrator-modelsDirect workspace dependent
vox-plugin-hostDirect workspace dependent
vox-telemetry-otlpDirect workspace dependent
KindSymbolSignatureSourceDescription
structaggregator::TaskAggregatepub struct TaskAggregatecrates/vox-telemetry/src/aggregator.rs#L17-L28Accumulated per-task statistics derived from emitted ModelCall events.
fnaggregator::record_task_startedpub fn record_task_started(task_id: u64)crates/vox-telemetry/src/aggregator.rs#L78-L85Record that a task has started, anchoring its wall-clock start time. Call this as early as possible when a task is created (e.g. at dispatch time when the task_id is first known). If not called before the first model-call event, [observe] sets started_at on first observation instead (less accurate but still non-zero).
fnaggregator::observepub fn observe(event: &TelemetryEvent)crates/vox-telemetry/src/aggregator.rs#L91-L104Observe a telemetry event and update the aggregate for the ambient task. Only ModelCall events with a task_id are accumulated. All other events are ignored. Called automatically by [crate::recorder::CompositeRecorder].
fnaggregator::takepub fn take(task_id: u64) -> TaskAggregatecrates/vox-telemetry/src/aggregator.rs#L109-L111Return the current aggregate for task_id and remove it from the map. Returns a zero-valued aggregate if no events were observed for task_id.
fnaggregator::fill_task_root_summarypub fn fill_task_root_summary(event: &mut TaskRootSummaryEvent)crates/vox-telemetry/src/aggregator.rs#L119-L132Populate a TaskRootSummaryEvent’s aggregate fields from the stored aggregate. Looks up and removes the aggregate for event.task_id. Fields left at zero if no aggregate is stored (e.g., task emitted no model calls). wall_time_ms is computed from started_at if available; callers may override afterwards if they have a more accurate measurement.
structconfig::TelemetryConfigpub struct TelemetryConfigcrates/vox-telemetry/src/config.rs#L14-L33Master telemetry configuration.
fnconfig::default_onpub fn default_on() -> Selfcrates/vox-telemetry/src/config.rs#L37-L48Returns the default config: local collection on, all categories on, remote upload off.
fnconfig::all_offpub fn all_off() -> Selfcrates/vox-telemetry/src/config.rs#L51-L62Returns an all-off config (used for tests and when master switch is disabled).
fnconfig::from_envpub fn from_env() -> Selfcrates/vox-telemetry/src/config.rs#L72-L112Resolve the active config from all five layers. Resolution order (highest wins): 1. Org-policy hard-off (/etc/vox/telemetry-policy.toml / %ProgramData%\vox\…) 2. User config (~/.config/vox/config.toml) 3. VOX_TELEMETRY master (off|on|debug) 4. Legacy per-category env vars 5. Default: local-on, remote-off, all categories on
fnconfig::from_env_legacypub fn from_env_legacy() -> Selfcrates/vox-telemetry/src/config.rs#L116-L118Backward-compatible alias for from_env.
fnconfig::is_master_enabledpub fn is_master_enabled() -> boolcrates/vox-telemetry/src/config.rs#L126-L143Returns true if telemetry is allowed at all (master switch is not “off”). This is the single check that legacy gates should consult before doing their per-category checks. When this returns false, NO telemetry should be emitted regardless of legacy env vars.
fnconfig::org_policy_disabledpub fn org_policy_disabled() -> boolcrates/vox-telemetry/src/config.rs#L166-L196Phase D — Layer 1: org-level hard-off via policy file. Reads the platform-standard policy file and returns true when the file contains an enabled = false directive, meaning the organisation has disabled all telemetry. The parse is intentionally simple (line-scan) to avoid pulling a TOML dependency into vox-telemetry. File paths: - Windows: %ProgramData%\vox\telemetry-policy.toml - Linux / macOS: /etc/vox/telemetry-policy.toml Missing file → returns false (policy not set; fall through to lower layers). Unreadable file → returns false with a debug log (fail-open).
enumconfig::ConsentStatepub enum ConsentStatecrates/vox-telemetry/src/config.rs#L225-L232User’s opt-in/opt-out state for remote telemetry upload.
fnconfig::is_remote_allowedpub fn is_remote_allowed() -> boolcrates/vox-telemetry/src/config.rs#L239-L241Returns true if remote telemetry upload is currently allowed. true iff the master switch is enabled AND the user has explicitly granted remote consent. An Unset consent state (first-run prompt not yet shown) is treated as Denied (conservative default — nothing goes out).
fnconfig::remote_consentpub fn remote_consent() -> ConsentStatecrates/vox-telemetry/src/config.rs#L247-L257Read the persisted consent state from ~/.config/vox/remote-consent. File contents: "granted" or "denied". Any other value (including a missing file) returns Unset.
fnconfig::set_remote_consentpub fn set_remote_consent(state: ConsentState)crates/vox-telemetry/src/config.rs#L264-L273Persist a consent decision to ~/.config/vox/remote-consent. Errors are silently swallowed — failing to write consent must never crash the application. If the write fails, remote_consent() will keep returning Unset on the next call, which means nothing is uploaded (fail-closed).
fnconfig::install_idpub fn install_id() -> Stringcrates/vox-telemetry/src/config.rs#L281-L294Return (or create and persist) a stable per-installation UUID. Stored at ~/.config/vox/install-id as a plain UUID string. On first call the file is created; subsequent calls return the cached value. Never panics — if reading/writing fails, returns a random UUID for this process invocation only (not persisted).
fnconfig::install_saltpub fn install_salt() -> [u8; 16]crates/vox-telemetry/src/config.rs#L302-L318Return (or create and persist) a 16-byte installation salt. Stored at ~/.config/vox/install-salt as 32 hex characters. The salt is used by vox-telemetry-otlp to hash session-id suffixes before upload; the salt itself is NEVER uploaded. If reading/writing fails, returns a random salt for this process invocation only.
structno_op::NoOpRecorderpub struct NoOpRecordercrates/vox-telemetry/src/no_op.rs#L4Default recorder used when no sink is registered. Discards all events silently.
traitrecorder::TelemetryRecorderpub trait TelemetryRecorder: Send + Sync + 'staticcrates/vox-telemetry/src/recorder.rs#L9-L11Trait implemented by every telemetry sink. record is called synchronously on the caller’s thread/task. Implementations MUST return quickly (fire-and-forget internally via tokio::spawn or a channel).
fnrecorder::set_global_recorderpub fn set_global_recorder(recorder: Arc<dyn TelemetryRecorder>)crates/vox-telemetry/src/recorder.rs#L17-L19Register the process-wide recorder. Silently ignored if called more than once (first writer wins). Call once at binary startup before any record_event!.
fnrecorder::global_recorderpub fn global_recorder() -> Option<&'static Arc<dyn TelemetryRecorder>>crates/vox-telemetry/src/recorder.rs#L24-L26Returns the global recorder, or None if not yet initialized. Used by the record_event! macro; callers should prefer that macro.
structrecorder::CompositeRecorderpub struct CompositeRecordercrates/vox-telemetry/src/recorder.rs#L29-L31Fan-out recorder: delegates every record call to all inner recorders.
fnrecorder::newpub fn new(inner: Vec<Arc<dyn TelemetryRecorder>>) -> Selfcrates/vox-telemetry/src/recorder.rs#L34-L36—
fnresearch_trial::validate_research_trial_metadatapub fn validate_research_trial_metadata(crates/vox-telemetry/src/research_trial.rs#L171Validate a research_trial.* row: known metric type, flat JSON object, allowlisted keys, scalar values, and bounded structural strings only.
structspan::TraceContextpub struct TraceContextcrates/vox-telemetry/src/span.rs#L12-L23Distributed trace context propagated through async task boundaries. Fields are Option so partial contexts are valid during the bootstrap phase.
fnspan::rootpub fn root(task_id: u64) -> Selfcrates/vox-telemetry/src/span.rs#L27-L35Create a root context (no parent).
fnspan::childpub fn child(&self, child_task_id: u64, child_agent_id: impl Into<String>) -> Selfcrates/vox-telemetry/src/span.rs#L38-L46Derive a child context for a sub-agent dispatch.
fnspan::current_trace_ctxpub fn current_trace_ctx() -> TraceContextcrates/vox-telemetry/src/span.rs#L67-L69Retrieve the current trace context or return a default empty context.
fnspan::current_trace_contextpub fn current_trace_context() -> Option<TraceContext>crates/vox-telemetry/src/span.rs#L72-L74Retrieve the current trace context, or None if no context is active.
enumtypes::TelemetryErrorpub enum TelemetryErrorcrates/vox-telemetry/src/types.rs#L16-L19Error returned by [validate_research_metric_row] and sink operations.
structtypes::TelemetryWriteOptionspub struct TelemetryWriteOptions<'a>crates/vox-telemetry/src/types.rs#L143-L145Repository-scoped session_id builder. Use with METRIC_TYPE_* constants.
fntypes::newpub fn new(repository_id: &'a str) -> Selfcrates/vox-telemetry/src/types.rs#L149-L151—
fntypes::session_benchpub fn session_bench(&self) -> Stringcrates/vox-telemetry/src/types.rs#L154-L156—
fntypes::session_syntaxkpub fn session_syntaxk(&self) -> Stringcrates/vox-telemetry/src/types.rs#L159-L161—
fntypes::session_mcppub fn session_mcp(&self) -> Stringcrates/vox-telemetry/src/types.rs#L164-L166—
fntypes::session_workflowpub fn session_workflow(&self) -> Stringcrates/vox-telemetry/src/types.rs#L169-L171—
fntypes::session_menspub fn session_mens(&self) -> Stringcrates/vox-telemetry/src/types.rs#L174-L176—
fntypes::session_routepub fn session_route(&self) -> Stringcrates/vox-telemetry/src/types.rs#L179-L181—
fntypes::session_lintpub fn session_lint(&self) -> Stringcrates/vox-telemetry/src/types.rs#L185-L187Session ID for vox.lint.* events (P2.1). Aggregator buckets by repo.
fntypes::session_repairpub fn session_repair(&self) -> Stringcrates/vox-telemetry/src/types.rs#L192-L194Session ID for vox.repair.* events (P2.1). One session id per repair invocation; the [RepairOutcomeEvent] closes it.
fntypes::session_auditpub fn session_audit(&self) -> Stringcrates/vox-telemetry/src/types.rs#L198-L200Session ID for vox.audit.* events (A11).
fntypes::validate_research_metric_rowpub fn validate_research_metric_row(crates/vox-telemetry/src/types.rs#L214Validate inputs before INSERT INTO research_metrics. Called by vox_db::VoxDb::append_research_metric on every write.
enumtypes::TelemetryEventpub enum TelemetryEventcrates/vox-telemetry/src/types.rs#L276-L342A single telemetry observation that may be routed to one or more sinks. New variants are added in later phases; each variant maps to one or more METRIC_TYPE_* constants. All variants are non_exhaustive so older sinks can ignore unknown events safely via _ => {} arms.
structtypes::FixtureModelIntentResolvedEventpub struct FixtureModelIntentResolvedEventcrates/vox-telemetry/src/types.rs#L346-L355Payload aligned with contracts/telemetry/fixture-model-intent-resolved.v1.schema.json.