tonic-observability - SKILL.md Agent Skill

name: tonic-observability description: Use Tonic's local observability harness for debugging compiler/runtime failures, native gates, parity, benchmark, and memory workflows. Helps decide when to enable telemetry and how to inspect bundles.

Tonic Observability

Use this skill when working on Tonic tasks where phase timing, error classification, emitted artifacts, or script-level correlation would help.

Enable it for

debugging compiler/runtime failures
tonic check, tonic run, or tonic compile failures where phase boundaries matter
native gates, differential/parity, benchmark, release, or memory workflows
any task where you want emitted artifacts and child runs grouped under one task view

Keep observability off for

Keep observability off for trivial formatting-only edits, quick read-only inspection, or tiny changes where normal stdout/stderr is already enough. Turn it on once diagnosis starts taking guesses.

Phase 1 workflow

Phase 1 is local-first and file-first. No extra services are required.

Single command

TONIC_OBS_ENABLE=1 cargo run --bin tonic -- check path/to/file.tn

Optional overrides:

TONIC_OBS_DIR=/tmp/tonic-obs
TONIC_OBS_TASK_ID=<task-id> to correlate related runs
TONIC_OBS_RUN_ID=<run-id> or TONIC_OBS_PARENT_RUN_ID=<run-id> when a wrapper already manages identities

Script workflow

TONIC_OBS_ENABLE=1 ./scripts/native-gates.sh

Top-level scripts create a root run plus child step runs under the same task.

Where to inspect bundles

Default root: .tonic/observability/

Important files:

latest.json — pointer to the most recent run summary
runs/<run-id>/summary.json — primary contract: command, status, phases, artifacts, normalized error
runs/<run-id>/events.jsonl — append-only event stream
runs/<run-id>/artifacts.json — emitted artifact manifest
tasks/<task-id>/runs.jsonl — compact index for correlated multi-run workflows

How to use the data

Open latest.json to find the last summary quickly.
Read summary.json first.
- status, exit_code
- phases[]
- error.kind, error.phase, error.source
- artifacts.emitted[]
If the run came from a script, open tasks/<task-id>/runs.jsonl to find child runs.
Use events.jsonl when you need step-by-step timing or script step boundaries.

Good defaults

Use telemetry for native gates before chasing failures across multiple scripts.
Use telemetry for benchmark and memory work when artifact paths matter.
Leave legacy knobs alone: TONIC_PROFILE_*, TONIC_DEBUG_*, and TONIC_MEMORY_* still work and are reflected in the run summary.

Phase 2

Phase 2 is optional future work: OTLP export and a disposable local UI stack. Do not assume it exists. Start with the local bundle every time.

For fuller operator-facing details, read docs/observability.md.