Skip to content
Trazum

Something that runs, and why it is not us

Documentation / Usage inputs · CI gates · Gateway

Everything in Trazum happens when somebody runs a command. The failures worth catching — a retry loop, a prompt that grew, a model swapped in a deploy — happen at 3pm on a Tuesday, and a report somebody runs three weeks later is an obituary.

So something has to run on a schedule. This page is about what that something is, why it is deliberately not a Trazum service, and exactly where that answer runs out.

The short version#

You needTrazum gives youYou supply
Measurements arriving on their owntrazum connect <provider>, idempotent over overlapping windowsThe scheduler
A crossing judged the afternoon it happenstrazum watch --once, whose state file survives a restartThe scheduler
An alert reaching a personA non-zero exit code, --json on stdout, --webhook <url>, and --notify for a desktop notificationThe inbox, the channel, the URL
Knowing the scheduler itself stoppedtrazum pulse --max-stale-hours <n>Somewhere that already runs on a schedule — your CI

These CLI schedules require no Trazum account or hosted control plane. Provider imports contact the provider you configure; optional webhooks send alerts to the endpoint you select. The optional web accounts and prompt library are separate from this local scheduling workflow.

What actually has to run#

Four things, and they are separate on purpose — a single "run everything" command would hide which of them stopped.

1. Pull. trazum connect <provider> --store writes measured usage into .trazum/store/. Re-pulling an overlapping window is idempotent: two records covering the same window, from the same provider, for the same model and grouping, are the same fact restated and the later pull wins. That is what lets an hourly job run over a rolling day without inventing money.

2. Judge. trazum watch --once reads the store, evaluates the gates you configured, and emits what crossed. It is the primitive; the foreground loop is this same function in a timer, so there is one code path and no daemon-only behaviour nobody exercises.

Its state file (.trazum/watch.json) is what makes a restart honest. Without it a resumed watcher re-alerts on yesterday's crossing — noise nobody reads — and implies it was watching the whole time, which is a claim it cannot make. With it, the crossing stays quiet and the unwatched stretch gets named once.

With no store at all, trazum watch --sessions --once judges the sessions Claude Code, Codex and Gemini CLI keep on this machine, the ones trazum bill reads, against the same budgets. Nothing is pulled and nothing is kept but that state file, which records the sessions' crossings apart from the store's. A crontab line for it is yours to write (proactive on writes the store's):

17 * * * * cd /srv/app && trazum watch --sessions --once --notify

--notify shows a desktop notification for what is new, through osascript, notify-send or a PowerShell toast, whichever the machine has. A cron job has no desktop session on Linux unless you hand it one (DISPLAY or DBUS_SESSION_BUS_ADDRESS), and when the notifier cannot show it the run says so and the exit code still carries the crossing. See the command reference.

3. Keep. trazum store --prune --keep <n> bounds the file a year of this produces. Nothing here needs the raw logs, which is what the privacy story required anyway.

4. Notice that 1–3 stopped. trazum pulse. See below.

Recipes#

Each of these runs the same command. Pick whichever your machines already have; none is better than the others and Trazum does not care which.

On Linux and macOS, trazum proactive on writes the watch line for you: one managed line in your crontab for the project you run it in, only after you say yes, and trazum proactive off removes it. It does not run connect, which reads from the provider over the network, so the line below that pulls is still yours. See speaking first.

cron — the exit code is the transport. A non-zero exit makes cron mail the output to the crontab's owner, which is alerting nobody had to build.

# Pull hourly, judge what it pulled.
17 * * * * cd /srv/app && trazum connect anthropic --store && trazum watch --once
# Keep the store bounded, weekly.
0 4 * * 0 cd /srv/app && trazum store --prune --keep 400

systemd timer — when you want the log in journalctl and a restart policy.

# /etc/systemd/system/trazum-watch.service
[Service]
Type=oneshot
WorkingDirectory=/srv/app
Environment=ANTHROPIC_ADMIN_KEY=…
ExecStart=/usr/local/bin/trazum connect anthropic --store
ExecStart=/usr/local/bin/trazum watch --once
# /etc/systemd/system/trazum-watch.timer
[Timer]
OnCalendar=hourly
Persistent=true

[Install]
WantedBy=timers.target

Persistent=true matters: a machine that was asleep runs the missed cycle on wake rather than skipping it silently.

GitHub Actions — when the machines are ephemeral and the store lives in the repository or an artifact.

Pinned by commit rather than by tag, which is what this repository does in its own workflows and for the same reason: a tag moves.

on:
  schedule:
    - cron: '17 * * * *'
jobs:
  watch:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - run: npx @trazum/cli connect anthropic --store
        env:
          ANTHROPIC_ADMIN_KEY: ${{ secrets.ANTHROPIC_ADMIN_KEY }}
      - run: npx @trazum/cli watch --once

GitHub disables scheduled workflows after a stretch of repository inactivity — sixty days, at the time of writing, and check their documentation rather than this page for the current number — and it does not tell you it happened. That is exactly the failure pulse exists for.

The week's bill, every Monday — for a repository whose logs are already in it (rotated JSONL under logs/, or whatever a converter wrote), the packaged spend gate on a schedule. since is computed by the job, because a budget "no period assumed" is only a weekly budget when the window is the week; and the report lands in the run summary, which is where a scheduled run's report can go — the Action's pull-request comment needs a pull request, and a cron has none.

on:
  schedule:
    - cron: '0 7 * * 1'
  workflow_dispatch:
jobs:
  bill:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
      - id: week
        run: echo "since=$(date -u -d '7 days ago' +%F)" >> "$GITHUB_OUTPUT"
      - uses: Davmunrey/Trazum@9b0b245b34fc672d79d04f5ca34090ace4916d0b  # 3.0.1
        with:
          usage-log: logs/           # a directory is read in name order as one bill
          since: ${{ steps.week.outputs.since }}
          max-usd: '200'             # the week's ceiling; exit 1 over it

A directory of mixed exports — transcripts beside a provider report — is trazum bill logs/ instead, which tells each file's shape and refuses what it cannot read by name; the Action's usage-log input is the plain-log door and takes what bill or a from-* command wrote.

Windows Task Scheduler — same command, same exit code.

schtasks /create /tn "Trazum watch" /sc hourly /tr `
  "cmd /c cd /d C:\srv\app && trazum connect anthropic --store && trazum watch --once"

The credential, in every one of them#

It is borrowed, never held. Trazum reads the key from a named environment variable, uses it for the request, and never stores it, logs it, returns it to a caller or puts it in a URL. What travels between parts of this tool is the name of the variable, not its value.

Each connector accepts two names — a TRAZUM_-prefixed one and the provider's own, so TRAZUM_ANTHROPIC_ADMIN_KEY or ANTHROPIC_ADMIN_KEY — and trazum connect <provider> --dry-run prints which ones it would look at without sending anything or needing a credential to say so.

So in each recipe above the secret lives where that platform already keeps secrets — a systemd Environment= line with the unit file mode you already use, a GitHub Actions secret, a Windows credential store. Trazum adds no new place for a key to sit, and there is no Trazum config field that holds one.

The thing that notices cannot be the thing that stopped#

watch --once writes its state file so a restart is honest. That file is read by exactly one thing, and that thing is the next cycle.

So until pulse existed, nothing could tell you the watcher had stopped, because the thing that would tell you was the thing that stopped. A dead cron produces silence, and a watcher with nothing to report produces silence too.

trazum pulse                        # the ages, judged by nothing
trazum pulse --max-stale-hours 36   # exits 1 when something stopped

Put that second line in the CI you already run on every push or every night. A dead cron becomes a red build on somebody else's schedule, and Trazum still hosts nothing.

Three things it will not do, each for the same reason the rest of this tool refuses things:

  • A first run that never happened is not late. There is no cadence to be late against, so never-run is its own verdict and never gates. A check that failed on "you have not adopted this feature" would be nagging, not measuring.
  • Without a threshold, nothing is judged. How stale is too stale is a policy, and a generated number nobody chose is a number nobody trusts.
  • How far the measurements reach is never judged by the same threshold. A store pulled ten minutes ago whose newest record stops two days back is a healthy job in front of a provider that reports late. Gating on it would be a red build for somebody else's latency.

Where this answer runs out#

Said plainly, because a page that only listed what works would be advertising.

  • If nothing of yours runs on a schedule, none of this helps. A laptop is not a scheduler. If the only machine is one that sleeps, the honest options are a CI cron or a small always-on host — both yours.
  • The last hop is still yours. Trazum can exit non-zero, print a document and POST to a webhook. It cannot page you, retry a delivery, deduplicate across channels or know you are on holiday. Those are the things a hosted alerting product is actually selling, and this is not one.
  • A watcher can only judge what has been pulled. A provider that reports usage a day late means a crossing is judged a day late, and no amount of scheduling fixes that. pulse reports the reach separately so the two delays are never confused.
  • Nothing here watches the watcher's watcher. If your CI stops running, pulse stops running with it. The chain has to end somewhere, and it ends at the thing you already trust to tell you when it breaks.
  • CI — gating a build on tokens, dollars and quality.
  • Usage logs — what can be read, and what each optional field unlocks.
  • JSON output — the pulse document and every other machine-readable one, field by field.
  • The doctrine — why a measured crossing and never a projection, and the rest of the reasoning above.