Configuration

All configuration lives under the :aurora_meter application key and is validated at boot by AuroraMeter.Config.validate!/0 (called from AuroraMeter.start_link/1), which raises on a missing required key, a wrong type, or a module-typed key naming a module that does not implement its behaviour.

Validation reads the whole :aurora_meter environment. A key that is not in the table below is reported, with the nearest known key named for you: in this release that is a warning at boot, and in Aurora Meter 1.0 it stops the boot. :ecto_repos, :included_applications and repo configuration written under this application (config :aurora_meter, MyApp.Repo, ...) are reserved and are never treated as Aurora Meter keys.

config :aurora_meter,
  repo: MyApp.Repo,
  pubsub: MyApp.PubSub,
  plans: MyApp.Plans,
  default_plan: :free,
  undeclared_feature_policy: :deny,
  feature_sources: %{tokens: :events},
  flush_interval: 5_000,
  broadcast_interval: 1_000

:feature_sources

Where each feature's commercial quantity comes from: :buffered (the ETS counter, flushed to aurora_meter_counters) or :events (the sum of the durable events AuroraMeter.record/4 writes). Anything the map does not name is :buffered, which is every feature in 0.4.x, so adding the key changes nothing until you name a feature in it.

A feature has exactly one source, and two boot checks hold that line:

Three call-time consequences, all covered in metering: AuroraMeter.track/4 and AuroraMeter.reserve/2,3 raise ArgumentError for an :events feature, AuroraMeter.with_quota/4 releases its reservation instead of committing it, and AuroraMeter.history/3 returns zeros.

The source is read once, at boot. Rewriting the key at runtime with Application.put_env/3 changes the declaration and not the behaviour: a source that could change between two calls inside one period is precisely the double count the key exists to prevent, so changing a source is a deploy.

:undeclared_feature_policy

A feature the tenant's effective plan does not declare is not a question Aurora Meter can answer, and until 0.5.0 it answered it permissively anyway. The policy says what to do instead. A feature some other plan declares counts as undeclared here: a :free tenant reaching a :pro only feature is exactly the case this exists for.

Every entry point keeps its documented return shape under every policy; only the value inside it changes. :warn behaves exactly as :allow and logs once per feature per node. :raise raises AuroraMeter.UndeclaredFeatureError, which carries the feature, the tenant key, the plan and the entry point.

track/4 is deliberately outside the policy and keeps counting: metering is not entitlement, and metering a name before it reaches a plan is a reasonable thing to do. It reports the condition as declared: in [:aurora_meter, :track] telemetry metadata instead. declared: there answers "does any plan declare this name", because answering "is this tenant entitled to it" would mean resolving the tenant's subscription on the hot path. AuroraMeter.entitled?/2 answers the entitlement question.

Upgrading from 0.4.x

# Keep the old behaviour exactly, and decide later:
config :aurora_meter, undeclared_feature_policy: :allow

The recommended sequence, in this order:

1. Run mix aurora_meter.features --strict. It lists what your configuration references that no plan declares, and every feature declared on some plans and not others, with the plans that would deny it.
2. Set :warn (the default in 0.5.x) and leave it for a release. Each undeclared feature logs once per node, which catches the names only reachable at runtime.
3. Fix the plans or the call sites, then set :deny.

A new install generated by mix aurora_meter.install starts at :deny.

:plan_version_conflict

A plan version is immutable. AuroraMeter.Plans.register!/0 runs at boot, stores a snapshot of each compiled version, and compares the fingerprint of every version it has seen before. Editing a price, a limit, a metered included count or unit price, a feature value or a recurring credit inside an existing version is a conflict.

config :aurora_meter, plan_version_conflict: :raise   # the 1.0 default
config :aurora_meter, plan_version_conflict: :warn    # the 0.5.x default

:raise fails the boot with AuroraMeter.PlanVersionConflictError, naming the plan, the version, both fingerprints and the remedy. :warn logs the same message through Logger.error/1 and continues.

Neither setting reprices anybody. A tenant is pinned to the version their subscription names and resolves that version's stored definition either way; the setting decides whether the host finds out at boot or in the log. The remedy is always to publish the change as a new version:

plan :pro, version: "2", effective_at: ~U[2026-10-01 00:00:00Z] do
  price 3_000
end

Upgrading from 0.4.x

Leave it at the 0.5.x default of :warn for one release. If the log is quiet, set :raise. If it is not, you have found a plan block somebody edited in place, and the stored definitions are in aurora_meter_plan_versions:

SELECT plan_id, version, encode(fingerprint, 'hex'), definition
FROM aurora_meter_plan_versions ORDER BY plan_id, version;

AuroraMeter.Plans.register!/0 is public, so a release task can run it (and rescue the exception) before the rolling deploy starts, which is also what you want when the subscriptions table is large enough that the first-boot assignment would be long. Do not call it inside a transaction of your own.

Module-typed keys with contracts

:tenant, :storage, :provider, :period_source, :clock and :plans are all checked at boot: the module must be loadable and must export every callback its behaviour declares and does not mark optional, or AuroraMeter.Config.validate!/0 raises an ArgumentError naming the key, the module and the missing callback. The required callbacks are read from the behaviour itself, so a new one is enforced without anyone updating a list. There is deliberately no probe call with a synthetic tenant, because a custom period source may legitimately raise for a tenant it does not know.

Two further boot checks are warnings rather than failures, because an existing install must still start: a :default_plan that no plan declares (an error from 1.0), and a metered feature whose unit_price is a float (integer minor units are the supported form).

One more check runs after the supervision tree is up, because it needs the database: every row in aurora_meter_credit_balances must carry :credits_currency (AuroraMeter.Credits.assert_currency!/0, which a host may also call from its own health check). A mismatch raises AuroraMeter.Credits.CurrencyMismatchError and the tree does not start; an absent table, or a repo that is not running yet, logs one :info line and boots.

:period_source must export current/2. containing/2 is optional. What it returns is checked on every call by AuroraMeter.Period.current!/2: a half-open UTC interval [start, end) containing the instant it was resolved for, or an AuroraMeter.Period.InvalidPeriodError naming the source module. The full contract, the error reasons and two recipes are in periods.

:clock must export now/0, today/0, monotonic_ms/0 and db_now/0. The only value supported in production is AuroraMeter.Clock.System; tests install AuroraMeter.Clock.Fixed through AuroraMeter.Test.with_clock/2, which is the supported way to freeze time. The four readings answer four different questions and are not interchangeable: in particular now/0 makes no monotonicity promise and db_now/0 is the one to compare against a persisted timestamp. See periods.

Subscription cache

AuroraMeter.plan/1 (and therefore every check, reserve and with_quota) resolves the tenant's subscription through AuroraMeter.Subscriptions, an ETS cache with a short TTL. Every write through AuroraMeter.Storage.put_subscription/1 evicts the entry locally and broadcasts the eviction on the configured PubSub, so other nodes drop it too. If you write to aurora_meter_subscriptions some other way, call AuroraMeter.Subscriptions.invalidate/1 afterwards (or set the TTL to 0).

Tenants

A tenant can be any term; it is resolved to a stable string key by the configured AuroraMeter.Tenant implementation (to_string/1 by default). For structs, provide your own:

defmodule MyApp.MeterTenant do
  @behaviour AuroraMeter.Tenant
  @impl true
  def to_key(%MyApp.Org{id: id}), do: "org:#{id}"
end

config :aurora_meter, tenant: MyApp.MeterTenant