hiveos-trace 0.1.6

Drop-in execution trace harness for non-deterministic workflows.

HiveOS Trace CLI Quickstart

hiveos-trace is a standalone CLI wedge extracted from HiveOS tracing concepts. It is built for operators and developers who want execution visibility, replay, and diagnosis without adopting the full HiveOS platform runtime.

Install

pipx install hiveos-trace

Alternative:

python -m pip install -U hiveos-trace

From source:

python -m pip install -e .

If hive is not recognized in your shell, use module form:

python -m hiveos.hive --help
python -m hiveos.hive trace ls

Zero-to-One

hive doctor
hive quickstart --no-open
hive trace ls --limit 5

CLI Surface (v0.1.6)

Top-level:

hive --help
hive --version
hive quickstart [--open] [--no-open] [--ui-url <url>]
hive doctor [--ui-url <url>]

Trace commands:

hive trace run [--name <label>] [--cwd <path>] [--timeout-sec <sec>] [--open] [--no-open] [--ui-url <url>] [--proxy] [--proxy-upstream <url>] [--proxy-port <port>] -- <command...>
hive trace replay <run_id> [--name <label>] [--cwd <path>] [--timeout-sec <sec>] [--open] [--no-open] [--ui-url <url>]
hive trace ls [--limit <n>] [--status <status>] [--json]
hive trace show <run_id> [--limit <n>] [--json]
hive trace tail [--run-id <id>] [--limit <n>] [--follow] [--json]
hive trace export <run_id> --bundle <path>
hive trace import --bundle <path> [--as-run-id <id>]
hive trace summary <run_id> [--event-limit <n>] [--tail-lines <n>] [--json]
hive trace diff <run_id_a> <run_id_b> [--event-limit <n>] [--tail-lines <n>] [--json]
hive trace diagnose <run_id> [--event-limit <n>] [--tail-lines <n>] [--json]
hive trace open <run_id> [--ui-url <url>]
hive trace archive <run_id> [--reason <text>] [--actor <label>]
hive trace unarchive <run_id>
hive trace prune --older-than <window> [--include-active] [--drop-events]
hive trace reconcile [--stale-after <window>] [--json]

hive trace ls --status values: all | active | archived | running | success | failed

Full release reference: docs/releases/hiveos-trace-command-reference-v0.1.6.md

Open Behavior

• quickstart, trace run, and trace replay default to no-open.
• Use --open to explicitly open UI for a run.
• --no-open always forces no-open.
• If --open is requested and the UI target is unavailable, Hive serves a local fallback run page.
• Set HIVE_TRACE_OPEN_ON_RUN=true if you want default-open behavior globally.

What This Gives You

• Run-level event lineage (observe_run_started, observe_run_finished)
• Step/output event capture from wrapped commands
• Checkpoint/rerun intent events for SDK-based flows
• Fast operator loop:
  • run (trace run)
  • summarize (trace summary)
  • tail (trace tail)
  • inspect (trace show)
  • compare (trace diff)
  • replay (trace replay)
  • diagnose (trace diagnose)
• Lifecycle hygiene (archive, unarchive, prune, reconcile)
• Team handoff path (export, import)

Run records are stored under ~/.hiveos-trace/runs. Default trace log path is ~/.hiveos-trace/logs/trace_events.log unless overridden.

SDK Integration (Optional)

from hiveos.observe import observe_run, observe_step

def my_pipeline():
    with observe_run("daily-sync", metadata={"team": "platform"}) as run_id:
        observe_step(run_id, "extract.start", payload={"source": "s3"})
        observe_step(run_id, "extract.finish", payload={"rows": 1203})

Checkpoint + rerun intent:

from hiveos.observe import observe_checkpoint, observe_rerun_request

observe_checkpoint(run_id, "ckpt-42", step_name="extract.finish", state_ref="state://pipeline/extract/42")
observe_rerun_request(run_id, from_checkpoint_id="ckpt-42", reason="retry with override")

Proxy Capture Mode (Optional)

hive trace run --proxy -- python agent.py
hive trace run --proxy --proxy-upstream https://api.openai.com/v1 -- python agent.py

Share Runs Across Machines

Export a run:

hive trace export <run_id> --bundle .\trace-bundles\run.bundle.json

Import on another machine:

hive trace import --bundle .\trace-bundles\run.bundle.json

If the same run id already exists, remap during import:

hive trace import --bundle .\trace-bundles\run.bundle.json --as-run-id observe-run:shared-001

Release Validation

Before public release:

1. Run .github/workflows/hive-trace-publish-testpypi.yml (manual dispatch).
2. Validate clean install from TestPyPI.

pipx install --pip-args="--index-url https://test.pypi.org/simple --extra-index-url https://pypi.org/simple" hiveos-trace
hive doctor
hive quickstart --no-open

Production release:

• Push tag format hiveos-trace-v<version> (example: hiveos-trace-v0.1.6) to trigger .github/workflows/hive-trace-publish-pypi.yml.