Usage tracking

ReportPlane tracks activity for quota enforcement, operational views, and usage reporting.

Three related systems#

Quota counters make fast runtime decisions for hourly, daily, and monthly windows. In Redis mode they use the reportplane:quota namespace.

Live metrics power recent-activity views and use the reportplane:live namespace in Redis mode.

Usage events provide durable reporting data. Production usage storage can create and validate a partitioned BigQuery usage_events table when configured.

Low-volume Assistant run and tool-invocation totals are persisted synchronously in the relational monthly usage rollup. This keeps plan enforcement recoverable without adding an Assistant-specific configuration or entitlement system. The runtime quota store remains the immediate enforcement path and is seeded from the persisted totals after Core restarts.

Notification delivery and Analytics Alert evaluation reservations use the same durable monthly-rollup pattern. Their workspace totals are returned by the subscription and workspace-usage APIs, displayed in Workspace limits and the Alerts plan-usage cards, and used to restore fast quota counters after Core restarts.

Assistant accounting is workspace-scoped:

• one accepted user message records one Assistant run;
• internal understanding/reasoning calls and the generated reply are not additional runs;
• one Core operation admitted through Assistant records one tool action;
• deterministic interaction fields and Confirm/Cancel transport do not independently add usage;
• manual actions outside Assistant do not use the Assistant allowance.

The current monthly totals are returned in workspace usage as assistant_runs_this_month and assistant_tool_invocations_this_month. The same values appear in the effective subscription response and the Console workspace limit panel. Monthly windows use UTC.

Usage dimensions#

Durable records are organized around event time and can include workspace, project, and usage-event type. The storage table is partitioned by event time and clustered for common workspace/project/event lookups.

Client last-used data#

Ingest clients, query clients, and API keys can display recent usage. API-key last_used_at is derived from usage rollups. The runtime only performs a conditional relational update when the last observed source IP changes, rather than writing on every request.

Cache backend#

The canonical cache configuration selects memory or redis for query result cache, live metrics, and quotas. Runtime authorization/configuration snapshots remain local memory in both modes and refresh separately from PostgreSQL.

Reading usage correctly#

Live values, quota counters, relational summaries, and durable usage reports can have different update timing. Use the view designed for the question you are asking rather than expecting every number to change simultaneously.