Usage, Metering & Capabilities

Metering records consumption events into a dedicated TimescaleDB hypertable through a non-blocking, loss-tolerant in-process recorder. Calls are buffered and batch-inserted on a size threshold, a flush interval, and on graceful shutdown — under back-pressure the recorder drops rather than blocking the request path, because metering is measurement, not audit.

Recording sites:

• logs.ingested.bytes and logs.ingested.events — recorded fire-and-forget after each log ingest (OTLP ingestion is metered too).
• spans.ingested — recorded after span ingestion, activating the tracing quota.
• storage.snapshot — a daily per-(organization, project) estimate of stored bytes, computed as the logical bytes ingested within the org's retention window. Engine-agnostic by design: it never scans the reservoir and ignores compression and manual deletions.

The dashboard surfaces all of this under a Usage section. Read APIs:

GET /api/v1/usage              # grouped totals and a daily series
GET /api/v1/usage/breakdown    # by type, project, service, and log level
GET /api/v1/usage/storage      # current estimate + daily storage trend
GET /api/v1/usage/capabilities # live usage vs each configured capability limit

A typed capability registry is the single source of truth for the platform's gates, limits and quotas, across three kinds:

Per-org overrides live in an organization_entitlements key-value table. A cache-backed resolver merges those rows over the registry defaults, fails open on database errors, and is swappable — a hosted distribution can source entitlements from subscription state without patching core. Overrides are edited from the Entitlements card on the admin organization page (boolean switches and numeric caps; an empty cap means unlimited). Members can read the merged set for UI gating:

GET  /api/v1/capabilities                            # merged set for the current org (UI gating)
GET  /api/v1/admin/organizations/:id/entitlements    # admin: read per-org overrides
PUT  /api/v1/admin/organizations/:id/entitlements    # admin: set per-org overrides

Usage quotas join metering to enforcement through a periodic in-process evaluator. It reads month-to-date totals for organizations that have at least one non-null quota cap and maintains an in-memory over-quota flag — so the ingestion hot path never touches the database for a quota check. Enforcement short-circuits on a null (unlimited) limit, which doubles as the defense when an admin lifts a cap.

When a limit or quota is hit, the global error handler returns a machine-readable code on the response (for example capability.alerts.max_rules.limit_reached), so clients and the dashboard can react precisely rather than parsing a message string.

The audit log is a structured security primitive backed by a canonical action registry — 70 typed actions across families like org.*, apikey.*, rule.*, auth.* and data.*. Because actions are a typed union, typos fail to compile, and the audit category is derived from the registry rather than hand-passed at each callsite.

Records capture the organization, the actor (user, API key, or system), the outcome (success / failure), and the request IP and user agent — read automatically from the request context, so callsites only state the action and target. Because actors now come from the request context, API-key access to query endpoints is audited too, and failed local logins are recorded as auth.login_failed with a failure outcome.

The audit page in settings exposes actor-type, outcome and time-range filters; the query API and CSV export carry the same columns. Retention is per organization: audit_retention_days (1–3650 days, or NULL to keep forever — the default) is editable from the admin organization page and enforced by the daily retention job.