netsky-db 0.1.6

netsky observability database
Documentation

netsky-db

Pure Rust observability database for messages, ticks, sessions, workspaces, clone dispatches, harvests, tool calls, git operations, directives, token usage, and watchdog events.

Stack

  • OLTP: redb key-value tables at ~/.netsky/meta.db.
  • OLAP: DataFusion SQL over Arrow RecordBatch snapshots.
  • Bridge: redb JSON rows decode into typed Rust structs, then register as DataFusion MemTables.

Usage

use netsky_db::Db;
let db = Db::open()?;
db.migrate()?;
let rows = db.query("SELECT COUNT(*) AS n FROM messages")?;

CLI:

netsky query "SELECT source, COUNT(*) AS n FROM messages GROUP BY source"

Schema v2

  • messages: inbound and outbound bus, iMessage, email, iroh, and demo source messages.
  • cli_invocations: command, argv JSON, exit code, duration, and host.
  • crashes: crash kind, agent, and detail JSON.
  • ticks: ticker and watchdog tick detail JSON.
  • workspaces: workspace create/delete lifecycle.
  • sessions: agent up/down/note events.
  • clone_dispatches: clone lifecycle, brief metadata, branch, status, exit code, and detail JSON.
  • harvest_events: source branch, target branch, commit SHA, status, conflicts, and detail JSON.
  • communication_events: normalized iMessage/email/agent communications with source, tool, direction, IDs, handle, agent, body, status, and detail JSON.
  • mcp_tool_calls: source, tool, agent, start/end, duration, success, error, timeout-race flag, and request/response JSON.
  • git_operations: git operation, repo, branch, remote, from/to SHAs, status, and detail JSON.
  • owner_directives: source, chat ID, raw owner text, resolved action, agent, status, and detail JSON.
  • token_usage: session ID, agent, model, input/output/cached tokens, cost in USD micros, and detail JSON.
  • watchdog_events: watchdog event name, agent, severity, status, and detail JSON.

Writer APIs

  • Db::record_message(MessageRecord): source message envelope.
  • Db::record_cli(...): CLI invocation metadata.
  • Db::record_crash(...): crash event.
  • Db::record_tick(...): ticker or watchdog tick.
  • Db::record_workspace(...): workspace lifecycle event.
  • Db::record_session(...): agent session event.
  • Db::record_clone_dispatch(CloneDispatchRecord): clone lifecycle and brief metadata.
  • Db::record_harvest_event(HarvestEventRecord): cherry-pick and harvest results.
  • Db::record_communication_event(CommunicationEventRecord): high-level communication audit events.
  • Db::record_mcp_tool_call(McpToolCallRecord): MCP tool timing, success, errors, and timeout races.
  • Db::record_git_operation(GitOperationRecord): local git mutations and pushes.
  • Db::record_owner_directive(OwnerDirectiveRecord): trusted owner directives and resolved actions.
  • Db::record_token_usage(TokenUsageRecord): model token and cost accounting.
  • Db::record_watchdog_event(WatchdogEventRecord): watchdog state transitions and escalations.

Query surface

netsky query registers every schema table in DataFusion:

netsky query "SELECT COUNT(*) FROM clone_dispatches"
netsky query "SELECT agent, SUM(input_tokens) FROM token_usage GROUP BY agent"

Compatibility

The Db::record_* writer API remains stable. Legacy SQLite meta.db files are archived to meta.sqlite-v1-<timestamp>.bak before redb creates the new store.