stella telemetry

Check, send, or delete the managed Oxagen Enterprise data queue. Off by default; needs a signed org enrollment to turn on.

stella telemetry controls the managed Oxagen Enterprise operational spool. This is a queue on your machine that holds content-free summaries of your runs, waiting to be sent to your organization.

It is off by default. If your machine has not been signed up through a managed org enrollment, every subcommand just prints enterprise telemetry: disabled (no managed enrollment) and exits with success. It makes no network calls and does not even build an HTTP client.

To learn what the managed export can and cannot contain, and how enrollment works, see Enterprise telemetry. This page only covers the command itself.

This page is not about your local telemetry. That data lives in .stella/private/store.db. It never leaves your machine on its own. You can read it with stella stats or the Observatory.

Synopsis

stella telemetry <status|flush|rollover-discard>

None of the three subcommands need a model provider or an API key. Managed export works independently of your model setup.

Subcommands

`stella telemetry status`

Shows whether you are enrolled, what is queued, and every loss counter.

stella telemetry status

If you are not enrolled, it says so. If you are enrolled, it prints one line covering:

pending

Rows and bytes waiting to be sent to the current sink.

stranded

Rows and bytes left over from an old sink. These will never be sent to the new sink. See rollover is not delivery below.

quarantine

Rows that could not be read. stella keeps some diagnostic details about them.

ledger_skipped

Rows skipped from the export ledger, split by reason: missing_rollup, malformed_nonce, malformed_rollup.

physical

How big the spool file is on disk. This is reported separately from the payload size because SQLite's own overhead (pages, indexes, WAL/SHM files, quarantine data) makes the file bigger than the data it holds.

dropped / corrupt_dropped / rollover_discarded

Three running counts of lost rows: rows dropped for running out of space, rows dropped for being corrupt, and rows discarded on purpose during a rollover. Each count only ever goes up.

If your enrollment is invalid or expired, the command fails with a clear error instead of pretending you are still enrolled. This command exists partly to catch a seat that has quietly stopped sending data.

The loss counters are why you should read the full status output, not just glance at it. A pending count of zero can mean "everything was delivered" or "everything was lost." Only dropped, corrupt_dropped, and rollover_discarded tell you which one happened.

`stella telemetry flush`

Tries to send one batch of data right now, then reports what happened.

stella telemetry flush

It prints how many rows were sent, plus the pending and dropped counts afterward. Every batch has limits:

≤ 50 events

The most events allowed in one batch.

≤ 256 KiB

The most data allowed in one request.

30-second lease

Rows are checked out, not deleted right away. If the flush crashes, the rows go back in the queue instead of being lost.

Delivery is at least once, and each row only goes to the sink it belongs to. A row is only marked as sent after a successful HTTPS response, and redirects are never followed. If sending fails for any reason (bad credentials, network trouble, server error), the row goes back in the queue and stella waits before trying again. The wait grows each time, from one second up to five minutes, with some randomness added (up to 25%) so retries do not pile up all at once.

stella already starts a quiet, best-effort flush on its own right after your enrollment is verified when it starts up. That attempt never slows down the agent, and stella does not wait for it to finish before shutting down. Run flush yourself when you need a delivery attempt that finishes before you move on, for example before taking a machine down for maintenance, or to check that a change to your org's intake worked.

`stella telemetry rollover-discard`

Permanently deletes rows left over from an old sink.

stella telemetry rollover-discard

This is the only destructive subcommand. It deletes the leftover rows for good and adds their count to the rollover_discarded total. There is no undo, and these rows were never delivered anywhere.

Rollover is not delivery

When your organization's sink changes, rows that were queued for the old sink are not automatically moved to the new one. Sending an organization's data to a sink it never approved would quietly reroute that data, so instead those rows become stranded. They stay stranded until you either restore the old enrollment, at which point they deliver as normal, or run rollover-discard to remove them.

Deleting stranded rows is always something you choose to do, and it is always counted. Rows lost to running out of space, rows lost to corruption, and rows lost to a rollover each get their own counter, so none of them can be mistaken for a successful delivery.

Exit behavior

Not being enrolled is not an error. All three subcommands print the disabled message and exit with code 0. That makes it safe to call this command from a script on any machine, whether or not it has a seat. A broken or expired enrollment is different: that is an error. The difference is between "this machine has no seat" and "this machine has a seat that stopped working."