SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillstonic-observability

tonic-observability

Deployment & operations

View repository

Updated 10-16 01:15

About this skill

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

  1. Open latest.json to find the last summary quickly.
  2. Read summary.json first.
    • status, exit_code
    • phases[]
    • error.kind, error.phase, error.source
    • artifacts.emitted[]
  3. If the run came from a script, open tasks/<task-id>/runs.jsonl to find child runs.
  4. 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.