opschain events stats

Included from Basic tier

opschain events stats [flags]

Aggregates the targeted server's event store over a window (EventService.GetEventStats — admin-scoped: the caller needs the /admin updatable determination): time-bucketed counts split by event class (api / warn / error / info / audit), the window totals, the most frequent event types and acting users, and — with --facet — counts by a payload field. The aggregation is computed set-based on the server; no rows are fetched, so an estate-scale window costs the same as a small one.

Drill into any figure with opschain events using the same filters: the statistics and the listing read the same store with the same vocabulary.

Flags

Flag	Meaning
--since <duration>	Window: this duration back from now (default 24h); ignored when --from is set.
--from <RFC3339> / --to <RFC3339>	Explicit window bounds; they go together.
--interval <width>	Bucket width: hour, day (default), week or month.
--time-zone <IANA>	Zone for bucket boundaries (default UTC).
--type <event type>	Only these exact event types (repeatable).
--prefix <type prefix>	Only types with these prefixes, e.g. warn: (repeatable).
--facet <payload field>	Also count by this payload field, e.g. applied_tier on info:agent:request, feature on warn:licence:feature_refused.
--limit <n>	Rows per ranked list (default 10, max 50).

-o json / -o yaml emit the response document verbatim (window echo, totals, by-class map, buckets, ranked lists).

Examples

The warnings heat strip for the last three days, bucketed hourly:

$ opschain events stats --since 72h --interval hour --prefix warn:
window: 2026-10-30T09:00:00Z .. 2026-11-02T09:00:00Z (hour buckets, UTC)
total: 14 (warn 14)
buckets:
  2026-10-30T11:00:00Z  2 (warn 2)
  2026-10-31T08:00:00Z  9 (warn 9)
  2026-11-01T22:00:00Z  3 (warn 3)
top types:
  warn:auth:login_failed                           9
  warn:licence:limit_approaching                   3
  warn:runner:version_skew                         2

Agent requests by applied tier this week:

$ opschain events stats --since 168h --type info:agent:request --facet applied_tier

Exit codes

Code	Meaning
0	Computed.
1	The read failed — a non-admin caller answers permission_denied.
2	Usage error, including a bad --interval, --since or --from/--to pair.