hiveos-trace 0.1.5

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

Observe Harness Quickstart

HiveOS includes a lightweight observe harness so users can add route visibility to existing workflows without adopting a new execution surface.

Install

Target package name:

pipx install hiveos-trace

Alternative:

pip install hiveos-trace

Until published, install from source:

pip install -e .

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

python -m hiveos.hive quickstart --no-open
python -m hiveos.hive trace ls

Release Validation

Before public release:

1. Run .github/workflows/hive-trace-publish-testpypi.yml (manual dispatch).
2. Verify 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.0) to trigger .github/workflows/hive-trace-publish-pypi.yml.

Zero-to-One (Under a Minute)

hive quickstart --no-open

Preflight checks:

hive doctor

What It Provides

• Run-level trace events (observe_run_started, observe_run_finished)
• Step-level trace events (observe_step)
• Checkpoint markers (observe_checkpoint)
• Rerun intent markers (observe_rerun_requested)
• CLI wrapper for existing commands (hive trace run -- ...)
• CLI run listing (hive trace ls)
• CLI run detail dump (hive trace show <run_id>)
• CLI run comparison (hive trace diff <run_id_a> <run_id_b>)
• CLI run replay (hive trace replay <run_id>)
• CLI run diagnosis (hive trace diagnose <run_id>)
• CLI run opening (hive trace open <run_id>)
• Lifecycle controls (hive trace archive, hive trace unarchive, hive trace prune)
• Run reconciliation (hive trace reconcile) to resolve stale running records

All events use the existing HiveOS trace sink (~/.hiveos-trace/logs/trace_events.log by default + /trace_events).

SDK Integration (Python)

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"})
        # ... your existing logic ...
        observe_step(run_id, "extract.finish", payload={"rows": 1203})

Checkpoint + rerun intent in SDK:

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")

CLI Wrapper Integration

Wrap any existing command:

hive trace run --name nightly-tests -- python -m unittest -q

UI open behavior:

• default is no-open (browser does not auto-launch)
• use --open to explicitly open UI for that run
• set HIVE_TRACE_OPEN_ON_RUN=true to restore default auto-open behavior
• --no-open always forces no-open
• if --open is requested and the UI target is down, Hive serves a tiny local fallback status page

Or:

hive trace run -- npm run test

This emits run start/finish + command step events and still returns the wrapped command exit code.

Inspect Captured Runs

List recent runs:

hive trace ls

Filter by lifecycle status:

hive trace ls --status active
hive trace ls --status archived

Open a run in local UI:

hive trace open observe-run:abc123

run will print the generated run_id, so open can be called immediately after execution.

Show detailed events for one run:

hive trace show observe-run:abc123

JSON output:

hive trace show observe-run:abc123 --json

Compare two runs quickly:

hive trace diff observe-run:abc123 observe-run:def456

Machine-readable diff:

hive trace diff observe-run:abc123 observe-run:def456 --json

Replay a run with lineage metadata:

hive trace replay observe-run:abc123 --no-open

Diagnose a run and get next-action hints:

hive trace diagnose observe-run:abc123
hive trace diagnose observe-run:abc123 --json

Archive / restore a run:

hive trace archive observe-run:abc123 --reason "completed review"
hive trace unarchive observe-run:abc123

Prune old runs (archived-only by default):

hive trace prune --older-than 30d

Optionally drop matching events from associated trace log files:

hive trace prune --older-than 30d --drop-events

Reconcile stale runs left in running state:

hive trace reconcile
hive trace reconcile --stale-after 10m

Optional Proxy Capture Mode

Capture OpenAI-compatible request/response traffic without SDK rewrites:

hive trace run --proxy -- python agent.py

Optional explicit upstream:

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

Environment Notes

• Harness writes through the same trace emitter used by HiveOS internals.
• Set HIVE_TRACE_LOG_PATH if you want traces written to a custom file path.
• To visualize harness output in Studio/Build trace views, point the UI/backend at the same trace store.

Intended Adoption Path

1. Add observe events only (no workflow behavior changes).
2. Add replay/diff analysis over captured runs.
3. Add operator interventions at selected step boundaries.