Skip to main content

Events & tracing

Every Versionx operation emits structured events. The same stream feeds the CLI's progress output, the TUI dashboard, the daemon's RPC notifications (forwarded to CLI/TUI/web/MCP clients), OTLP export, and the state DB's run history.

Enabling​

On stderr (human-friendly)​

VERSIONX_LOG=debug versionx sync

As newline-delimited JSON​

versionx sync --output ndjson | jq

Over OTLP​

export VERSIONX_OTLP_ENDPOINT=http://localhost:4317
versionx sync

Event shape​

{
  "id": "uuid-v7",
  "timestamp": "2026-04-18T14:02:17.123Z",
  "kind": "adapter.exec.stdout",
  "level": "info",
  "message": "pnpm install",
  "data": { }
}

Kinds emitted today​

Scanner found 15 distinct kinds across the workspace, grouped below by top-level category.

adapter​

  • adapter.exec.complete
  • adapter.exec.start

config​

  • config.detect.start
  • config.init.complete

release​

  • release.apply

runtime​

  • runtime.download.complete
  • runtime.download.start
  • runtime.install.complete
  • runtime.install.start
  • runtime.resolve.fetch
  • runtime.resolve.start
  • runtime.verify.complete
  • runtime.verify.fetch
  • runtime.verify.skipped

state​

  • state.backup

Consumption​

From an AI agent​

Agents connected via MCP receive events as progress notifications on streaming tool calls.

From Rust (SDK)​

use versionx_sdk::{Core, EventBus};

let bus = EventBus::new();
let mut rx = bus.subscribe();
let core = Core::builder().event_bus(bus).build().await?;

tokio::spawn(async move {
    while let Ok(event) = rx.recv().await {
        if event.kind.starts_with("policy.") {
            eprintln!("{event:?}");
        }
    }
});

From a shell​

versionx sync --output ndjson \
  | jq 'select(.kind | startswith("adapter."))'

See also​