Files
appwrite/bin/worker-stats-usage
Chirag AggarwalandCursor Agent dadc4aa12f feat: add self-hosted usage service (#13286)
* feat: add self-hosted usage service

* fix: make usage stack CI-ready

* fix: mark usage setup image buildable

* fix: gate Appwrite on usage schema setup

* test: initialize usage project before API keys

* fix: prevent usage ingestion from starving workers

* refactor: set up the usage schema at boot, not in a one-shot container

Every other schema in self-hosted Appwrite is created at boot by
app/http.php -- platform DB, project DB, shared-tables metadata, bucket
collections -- with a retry ladder and an already-exists skip. Usage was
the only one with its own container, and Cloud has no equivalent: there
an operator runs the setup script by hand against the migration endpoint.

Gating `appwrite` on `service_completed_successfully` also meant an
unhealthy ClickHouse stopped the API from starting at all, which lets
analytics storage take down the core API. The gating was inconsistent
too: only the dev override waited on the one-shot, so in the shipped
compose it was an orphan sitting at Exited (0), which reads as a failure.

Call Connection::setup() from the existing boot block instead. It retries
on the same 15x2s ladder as the databases above so a cold start wins the
race against ClickHouse, then gives up with a warning rather than
blocking boot. Reads and ingestion already gate on Connection::isReady(),
so both stay correct while the schema is missing.

Keep bin/usage-setup and the CLI task -- they repair a dropped table
without a restart, the closest analogue to Cloud's manual script -- and
put its retry on the same ladder.

* refactor(usage): open the read endpoints for edition-specific policy

Cloud has to enforce plan history limits, the premium geo addon, and its
affiliate metric carve-out on the same two endpoints, and today it does
that by keeping a full copy of both actions. The copies have already
drifted behind this branch's gauge fixes, so the duplication is actively
losing correctness rather than merely costing lines.

Make the upstream actions subclassable instead:

- widen the dimension/filter/interval constants and the query helpers from
  private to protected
- read them through `static::` so an override actually takes effect --
  `self::` binds to the defining class and would silently ignore Cloud
- inject a `usagePolicy` object the actions consult before querying. The
  self-hosted implementation allows everything, since self-hosted has no
  plans, addons, or reseller namespaces. Cloud binds a subclass that
  carries the checks its endpoints do today.

The policy is injected rather than hung off the action because actions are
shared across coroutines, so per-request state cannot live on `$this`.

Also fold `country` filters through Context::normalizeCountry() on the way
in. Writes have always stored the column lowercased, readers did not fold
the filter, and ClickHouse compares case-sensitively -- so
`equal("country", ["US"])` returned an empty series. Both sides now share
one rule, with a unit test pinning them together.

* chore: ignore the .pi scratch directory

* docs(usage): explain the realtime concurrency constants

Cloud carried these two constants with the rationale attached; upstream
now owns them, so bring the reasoning along rather than leaving bare
values here and a duplicate definition there.

* refactor(usage): extract realtime concurrency sampling into a library

Cloud's stats-resources task carries a near-verbatim copy of this fold --
same method names, same three constants, same values -- so the two editions
each own an arithmetic they should agree on. They had already diverged:
Cloud opens its first window at `_APP_STATS_RESOURCES_INTERVAL` unfloored,
so an interval below the 300s bucket size yields a window that closes
before any whole bucket has elapsed and samples nothing at all.

Subclassing does not work here: this task injects `usageConnection`, which
Cloud's container does not define, and inject() is positional and cannot be
dropped by a subclass. The fold is a well-defined domain concept and takes
only a Usage instance, so it becomes Appwrite\Usage\Concurrency and both
editions call it.

Task drops 157 -> 63 lines. The flooring fix lives in the shared code, with
a unit test that fails on the old unfloored behaviour.

* ci: run the Usage e2e suite

The suite was added with the endpoints but never wired into the E2E
matrix, so it has not run in CI once -- the endpoints were only ever
covered by whatever ran locally.

ClickHouse is in the default compose profile, so `compose up --wait`
already starts it; the job needs no other setup. Marked functional so
paratest parallelizes the single class per method, matching the other
one-class suites.

* fix(usage): resolve the PHPStan failures on the boot setup and test fake

Two real defects the project-wide scan caught:

- app/http.php annotated $usageConnection with an aliased class name that
  PHPStan would not resolve in that docblock, so isEnabled() and setup()
  were both calls on an unknown type. Use the fully-qualified name and drop
  the now-unused alias.
- the test fake bound $queued by reference before checking isset(), which
  created the array key as a side effect and made the guard always true.
  Read through the key instead and shift in place.

Also return the Context setters to `static` rather than `self`, so a
subclass can chain them. Cloud adds a team dimension on top of this class
and chains its own setter after a dozen inherited ones; with `self` the
chain degrades to the base type halfway through and the subclass method is
unreachable. That is what kept Cloud's copy of every setter alive.

* refactor(usage): own the usage workers and tasks in the Usage module

Three of the five _APP_EDITION checks this branch added were the wrong
mechanism for what they were guarding.

The one in Platform\Appwrite was simply dead: Cloud composes Core() plus
its own modules through Appwrite\Cloud\Platform\Appwrite and never
instantiates this class, so the guard could not fire there.

The two in the shared Core services were load-bearing but env-dependent.
Cloud registers its own stats-usage and stats-resources, and Core is added
first, so without a guard getWorkerAction() would hand Cloud the generic
worker instead of its billing-aware one -- silently, and only when
_APP_EDITION happened to be unset.

Move both registrations into the Usage module's own Services/Workers.php
and Services/Tasks.php, which is where Databases and Functions already keep
theirs. Cloud never registers that module, so the collision cannot occur
regardless of environment. Verified with _APP_EDITION unset: Cloud drops
from three duplicated usage actions to none, and usage-setup is no longer
registered there at all, which matches Cloud provisioning its schema
out-of-band.

The remaining two guards stay, for reasons that are not registration:
Deletes would begin purging Cloud's usage rows on project deletion, and
Schedule would run a second usage loop alongside Cloud's own scheduler.

* chore(usage): drop the new unit tests and widen the usage constraint

Removes the unit tests this branch introduced. The e2e suite covers the
usage endpoints, and tests/unit/Usage/Fakes/Adapter.php only existed to
serve them.

Also allow utopia-php/usage ^0.14.0 rather than pinning 0.14.0 exactly, so
patch releases come in without a lock edit. The lock still resolves 0.14.0;
only its content hash changed.

RegistrationTest keeps its Usage service entry -- that is not new coverage,
it is the existing duplicate-worker assertion following the registration
move.

* refactor(usage): split the policy hook into three assertions

Cloud's merged entitlement work asserts access, geo dimensions and history
at three different points, and it has to: access is checked before the
request is parsed so an unauthorised caller is refused rather than told
whether their query was valid, while the geo gate needs the parsed filters
and the history check needs the resolved window.

A single assert() could only run after parsing, which turned that 401 into a
400. Match the three-call shape so Cloud can inherit the query unchanged.

Gauges asserts history only, as Cloud's does -- it has no geo dimensions and
no metric carve-out.

* style(usage): type the concurrency constants

Cloud's version of this class, merged in appwrite-labs/cloud#5399, typed
these; keep that when the two converge here.

* chore: ship console 0.6.0 with self-hosted usage

vibes 0.6.0 includes appwrite/vibes#155, which enables the usage screens
against the endpoints this branch adds. Older console builds have no UI for
them.

* fix(usage): expire readiness cache and purge team project tenants

ClickHouse readiness was cached forever after the first success, so later
outages were treated as healthy and usage writes were dropped. Team-owned
project deletes also never reached the tenant purge path.

* feat(usage): emit unified per-resource storage gauges on self-hosted

The self-hosted stats-resources worker only counted rows, so the console's
storage charts — which read the unified `storage` gauge Cloud writes per
bucket, database, function, and site — stayed empty. Port Cloud's
collectUnifiedStorage projection: per-resource storage bytes plus the
files/collections/documents/deployments/builds companions and project
totals, with explicit service/resourceType/resourceId tags.

Flat dimensioned gauge aggregates also returned time: null, which crashes
the console's top-resources parser; the window end now stands in, matching
the flat max-aggregate precedent.

* chore: ship console 0.6.1

* fix(usage): purge tenants before the delete removes their mapping

Team deletion removed the platform project records inside the action and
purged ClickHouse afterwards, but retries reconstruct tenant sequences
from those records — a purge failure after the delete left the tenants
unrecoverable. Purge first, so a failure fails the message while a retry
can still resolve the mapping, and sweep again after the delete for rows
that landed in between (best-effort, logged). A purge returning false now
also fails the message instead of being silently acknowledged.

* fix(usage): land review typing, errors, and static hooks

Type the request usage context, split disabled vs schema-not-ready
catalog errors, and late-bind overridable interval constants.

Co-authored-by: Chirag Aggarwal <chiragaggarwal5k@gmail.com>

* fix(usage): span the swallowed post-delete tenant sweep

Keep the best-effort Console::error, and add Span attributes so a
failed sweep is visible on the worker span, not only stdout.

Co-authored-by: Chirag Aggarwal <chiragaggarwal5k@gmail.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
2026-08-24 10:32:42 +05:30

4 lines
66 B
Bash
Executable File

#!/bin/sh
exec php /usr/src/code/app/worker.php stats-usage "$@"