Skip to main content
Version: v5.7.0

opschain admin providers usage

Included from Basic tier

opschain admin providers usage --kind <kind> [--code <code>] [--grain day] [--from 30d] [--to <when>]
                               [--metric <metric>] [--by project|detail|agent|grant] [--project <code>]
                               [--timezone <zone>] [-o json|yaml] [--server <url>] [--auth-token <token>]

Shows one provider family's usage (v2 ModelUsageService.ListProviderUsage): one row per bucket, provider and metric over the window at the grain — every metric the family records (opschain docs provider-usage, "The families and their metrics") — with the peaks that survive aggregation and one total per metric. The same verb for every family: --kind secrets --code vault-prod answers how hard OpsChain is hitting that vault, --kind image_registry how many pushes failed this week, --kind siem how far behind the feed is. Needs the provider-record administrator's verdict.

Flags​

FlagMeaning
--kind <kind>Required. The family: secrets, transport, model, image_build, image_registry, identity, siem, otlp, github or jsm.
--code <code>One provider's code. Default: every provider of the family, each keeping its own rows.
--grain <grain>minute, hour, day (default), week, month, quarter or year. Minute buckets are UTC; every other grain is a bucket on the calendar the rows were rolled under.
--from <when>Window start: a relative age (30d, 2w, 12h), an RFC 3339 instant or a YYYY-MM-DD date (UTC midnight). Default 30d.
--to <when>Window end, same forms. Default: now.
--metric <metric>Narrow the rows to one metric of the family. Default: every metric.
--by <dimension>Keep one more dimension per row: project, detail (the model a model call reported, the image a push carried), agent or grant. Default: one row per bucket, provider and metric.
--project <code>Narrow the rows to one project. Platform-level rows (an identity exchange, a SIEM ship) carry no project.
--timezone <zone>IANA zone the bucket labels are rendered in. Default: the reporting zone. Bucket boundaries never move.
--server <url>Server base URL. Default: the active context, then OPSCHAIN_SERVER.
--auth-token <token>Bearer token override. Default: your opschain login session, then $OPSCHAIN_ADMIN_TOKEN, then the token stored by opschain admin login for that server.

Output​

The table lists one row per bucket, provider and metric (and the --by dimension): BUCKET (the label in the rendering zone), CODE, METRIC, COUNT (samples — a counter's count), ERRORS, VALUE (a counter's count, a value metric's quantity — tokens, bytes, seconds), MAX (the largest single sample), LATENCY MS (the summed latency where the seam times the call) and PEAK MIN (the busiest minute inside the bucket), followed by a totals line naming each metric's figure and the calendar.

For one model provider (--kind model --code <code>) whose record carries a provider-level model budget, a token budget block follows: one line per window with a ceiling — the spend so far, the ceiling, what remains, the fraction used and the local boundary the window resets at (opschain docs model-providers):

token budget (provider ceiling across every agent and call):
  day      120000 of 500000 tokens spent, 380000 remaining (24%) — resets 2026-11-13T00:00:00+10:30
  month    7900000 of 8000000 tokens spent, 100000 remaining (98%) — resets 2026-12-01T00:00:00+10:30

-o json / -o yaml carry from, to, grain, group_by, timezone, calendar (timezone, fiscal_year_start), totals (one entry per metric the family registers: metric, metric_kind, count, errors, value_sum, value_max, latency_sum_ms, latency_max_ms), rows (opschain docs resources/model_usage, ProviderUsageRow) and token_budget (one entry per budgeted window: window, cap, used, remaining, fraction, window_start, resets_at; empty for every other family and for a provider with no ceiling).

Exit codes​

CodeMeaning
0The usage was printed (an empty window prints no provider usage in the window).
1The server refused or failed the request (a rejected credential, an unknown family, a metric the family does not record, a malformed window).
2Usage — no --kind, a malformed --from/--to, or no server / credential resolvable.

Named errors​

  • --kind names the provider family: secrets, transport, model, image_build, image_registry, identity, siem, otlp, github or jsm — exit 2.
  • invalid --from "<value>": expected a relative age (30d, 2w, 12h), an RFC 3339 instant or a YYYY-MM-DD date — exit 2.
  • kind must be one of secrets, transport, … / metric is not a metric the <kind> family records / grain must be minute, hour, day, week, month, quarter or year / group_by must be project, detail, agent or grant / timezone is not an IANA time zone name / from must be before to — the server's field violations, exit 1.
  • a server is required — pass --server <url>, set OPSCHAIN_SERVER, or 'opschain context use <name>' — exit 2.
  • the server rejected the credential — run 'opschain login' again, or check the admin token — exit 1.

Examples​

Daily reads, cache hits and lease mints against one vault over the last month:

opschain admin providers usage --kind secrets --code vault-prod

The last hour of SIEM shipping, minute by minute, as JSON:

opschain admin providers usage --kind siem --from 1h --grain minute -o json

Which projects push the most images through a registry this quarter:

opschain admin providers usage --kind image_registry --code ghcr-prod --grain quarter \
  --metric pushes --by project
  • usage.timezone, usage.fiscal_year_start — the reporting calendar (project override).
  • usage.minute_retention, usage.hour_retention — how far back the minute and hour grains reach.

See also​

  • opschain docs provider-usage — the component page.
  • opschain docs cli/admin-providers-overview — every provider's health and today's figures.
  • opschain docs cli/agents-usage — the model lane's token summary.