API inventory

Everything Aurora Meter (the free core) offers a host application, with a stability class per entry. It is the authority for what the support policy covers: see Support policy.

If something is not on this page, it is not part of the supported surface, even when the module or function happens to be public in the compiled code.

test/aurora_meter/api_inventory_test.exs checks this page against the code on every mix test. Every Module.function/arity below must exist, no internal module may be listed, and every telemetry event and PubSub tag must appear verbatim in lib/.

How to read this page

Since is the package version that introduced the entry. 0.5.0 marks an entry that is written but not yet published; it ships in the transition release.

Test helpers (AuroraMeter.Test, AuroraMeter.Clock.Fixed) are stable, but they are for host test suites. Nothing in production should depend on them, and the support policy governs them under its own heading rather than by SemVer on every helper name.

1. Facade functions

1.1 AuroraMeter

1.2 AuroraMeter.Events

The read side of AuroraMeter.record/4, plus the one function a host needs when it wraps a record in a transaction of its own. See Metering.

1.3 AuroraMeter.Entitlements

The facade delegates to this module and is the recommended entry point. The functions are listed because they are public, documented and called directly by existing hosts.

1.4 AuroraMeter.Credits

Micro-dollar integers throughout. See Credits.

1.5 AuroraMeter.Credits.Money

1.6 Plans

1.7 Periods and the clock

1.8 Storage dispatchers

Each function dispatches to the configured :storage module. The callbacks are in section 2.

1.9 Subscriptions, flusher, live updates

1.10 Configuration accessors

1.11 Billing seam

1.12 Schema helpers

1.13 HEEx components (optional dependency)

Compiled only when Phoenix.Component is loaded. Without phoenix_live_view and phoenix_html the module does not exist at all, which is not an error: everything else in this inventory works headless.

1.13a The entitlement plug

Compiled only when Plug.Conn is loaded. Without plug the module does not exist at all, which is not an error. It is advisory: it takes no reservation, so between its decision and the controller's work another request on the same node can consume the last unit. The strict admission is AuroraMeter.with_quota/4 around the work itself, and no reserving plug is shipped. See Phoenix.

1.14 Retention

Deletes the operational rows the allow list names, and nothing else. Financial history is never deleted, at any age, under any option. See Retention.

1.15 Oban workers (optional dependency)

Compiled only when Oban is loaded. Without it the whole AuroraMeter.Oban namespace is absent, which is not an error: every operation these workers wrap is a public function any scheduler can call. See the scheduler map.

1.16 AuroraMeter.Credits.Lots

The public read side of credit lots: what a grant is worth now, what moved it, and which lots a payment funded. Read only, no locks, a snapshot. It is the only supported route to lot data from outside AuroraMeter.Credits. See Credits.

A wallet that has not been cut over to lots has none, and every function here answers [] or nil for it.

1.17 AuroraMeter.Credits.LotMigration

The wallet migration onto credit lots (schema step S5). Shadow by default, one transaction per wallet, and it never cuts a wallet over unless the replay reproduces that wallet's balance, held and promotional exactly. See Upgrading to lots.

1.18 AuroraMeter.Credits.Recurrences

Recurring credit allowances: one grant per tenant, entitlement, plan version and period, with a capped rollover and a bounded catch-up after downtime. The policy is a plan property (AuroraMeter.Plans.recurring_credits/2); a plan that declares none grants nothing. Pause it with AuroraMeter.Operations.pause("credits_recurrences:global"). See Credits and Plans.

1.19 AuroraMeter.Telemetry

The telemetry contract: the event catalogue as data, the closed tag allow list, the redaction helper and the on-demand gauges. See Telemetry.

1.20 AuroraMeter.Telemetry.Metrics (optional dependency)

Without telemetry_metrics installed the module is not defined at all. Every event is still emitted and AuroraMeter.Telemetry still works; nothing in lib/ references this module.

1.21 AuroraMeter.LiveDashboard.Page (optional dependency)

A Phoenix.LiveDashboard page showing what Aurora Meter is doing on this node. It is registered with additional_pages: and it requires the :authorized_by option: there is no default and no implicit allow. The three accepted forms, and why the core page accepts :host_route while the Pro page refuses it, are in AuroraMeter.LiveDashboard.Auth.

The page renders no tenant key, feature name, reference or event id: every figure on it is a node-local aggregate, a checkpoint position or a configuration value. A section it could not read renders the word "unavailable" with an error class, never a 0 and never an empty table. A gauge-derived figure whose last sample is older than three :metrics_intervals renders as stale with the sample age.

1.22 AuroraMeter.OpenTelemetry (optional dependency)

Attaches :telemetry handlers that turn Aurora Meter's slow operations into OpenTelemetry spans in the host's own SDK. It uses the OpenTelemetry API and only the API: it starts no tracer provider, no exporter and no batch processor, and opens no socket. With the API present and no SDK configured, the no-op tracer swallows everything.

The span attributes are redacted (AuroraMeter.Telemetry.redact/2), so no tenant key, reference, object id or provider reference reaches a tracer, and a failure sets the span status with an empty message: a status message is free-form text and there is nothing safe to put in it.

The hot path is not instrumented: [:aurora_meter, :track], [:aurora_meter, :reserve], [:aurora_meter, :broadcast], [:aurora_meter, :cluster, :apply] and every gauge produce no span unless the caller names them in :events.

2. Behaviours and their callbacks

A host or an extension implements these. Adding a required callback to one of them is a breaking change for implementers and does not happen during 1.x.

The implementations the core ships:

AuroraMeter.Config.validate!/0 checks at boot that every module-typed key names a module that exists and exports every callback its behaviour declares and does not mark optional. The callback list is read from behaviour_info/1, never copied.

3. Structs and public types

Named types a host will meet in a spec: AuroraMeter.Period.t/0, AuroraMeter.Entitlements.quota/0 and AuroraMeter.Entitlements.check_result/0, AuroraMeter.Credits.balance/0, AuroraMeter.Credits.money_point/0, AuroraMeter.Credits.money_total/0, AuroraMeter.Credits.summary/0 and AuroraMeter.Credits.txn/0, AuroraMeter.Credits.Money.micro/0, AuroraMeter.Storage.counter_row/0, AuroraMeter.Storage.history_row/0, AuroraMeter.Storage.history_point/0, AuroraMeter.Storage.event_row/0, AuroraMeter.Storage.counter_delta/0, AuroraMeter.Storage.history_delta/0, AuroraMeter.Storage.counter_total/0, AuroraMeter.Storage.correction_entry/0 and AuroraMeter.Storage.history_total/0, AuroraMeter.Plan.t/0 and AuroraMeter.Plan.feature_config/0, AuroraMeter.Clock.Fixed.unit/0, and AuroraMeter.Schema.CreditTransaction.kind/0, AuroraMeter.Schema.CreditTransaction.category/0 and AuroraMeter.Schema.CreditTransaction.status/0.

4. Return values and error tuples

Aurora Meter 0.x grew three return families, and they are not uniform. Listing them as if they were would be a false claim, so they are stated as they are, with the one change 1.0 makes.

Entitlement family. check/2 returns :ok | {:error, :limit_exceeded | :not_entitled}. allowed?/2 and entitled?/2 return booleans. remaining/2 returns non_neg_integer() | :unlimited. quota/2 returns the quota() map. reserve/2,3 returns the same shape as check/2. with_quota/3,4 returns {:ok, result} | {:error, term()}. Every one of these keeps its shape under every undeclared_feature_policy; the policy changes the answer, never the shape. Under :raise they raise AuroraMeter.UndeclaredFeatureError instead of answering.

Credits family. grant/3 and grant_with_status/3 return {:error, Ecto.Changeset.t()}, while hold/4, settle/3, release/1, debit/4, reverse/4 and with_credits/4 return a bare atom reason (:insufficient_credits, :debt_outstanding, :duplicate_reference, :not_found, :already_settled). This inconsistency changes in 1.0: the grant functions move to the atom family, and the migration note will name the exact mapping. A caller that matches {:error, %Ecto.Changeset{}} on a grant today should expect to revisit it, and it is called out here rather than papered over.

Refusals never roll back the caller's transaction. Every refusal in the ledger is decided before anything is written and returns {:error, reason}.

Idempotency keys. The credit ledger keys on reference: (a string). Aurora Meter Pro's outbox payload uses identifier internally. There is one rule and this page states it rather than inventing another: an idempotency key option is named reference: for credits, and id: for events.

Money. Micro-dollar integers in the ledger, minor units (cents) at provider boundaries through AuroraMeter.Credits.Money. A plan's price and a metered unit_price are in cents. Financial values never round inside a transaction.

5. Configuration keys

Every key is validated by NimbleOptions at boot. An unknown key is reported with the nearest known key named: a warning in 0.5.x, a refusal to boot in 1.0. :ecto_repos, :included_applications and repo configuration written under the same application (config :aurora_meter, MyApp.Repo, ...) are reserved and are never treated as Aurora Meter keys.

6. Telemetry events

Event names, measurement keys and metadata keys are covered by SemVer. The Matched in lib/ column holds the event name as AuroraMeter.Test.TelemetryCensus reads it out of the parsed source, so a renamed event fails the build. A name whose last segment is computed is written with the computed segment's own name ([:aurora_meter, :credits, kind]), and the family it stands for is enumerated by AuroraMeter.Telemetry.events/0.

declared was added to the track and reserve metadata in 0.5.0, which is an additive change: a handler matching on the old keys is unaffected.

record is a span, not a flat event: an OpenTelemetry bridge has to be able to open it before the database work starts, so Ecto's own spans nest inside it, and a span reconstructed after the fact cannot parent a child that was already emitted. :telemetry.span/3 emits :start, :stop and :exception under the [:aurora_meter, :record] prefix; metrics presets read :stop, where duration and count are the measurements. result is :inserted, :duplicate or the error tag (:invalid, :conflict, :unavailable, :unsupported), and projection is :ok, :cold or :projection_failed, which is how a committed event whose in-memory view could not be updated stays visible without becoming an error.

The backfill batch event is emitted once per committed batch of mix aurora_meter.events.backfill. It is the only observable a long backfill has, and cursor is the seq an interrupted run resumes from.

The two replay events are AuroraMeter.Events.Replay.run/1's observables. [:aurora_meter, :replay, :batch] fires once per committed batch with phase: :scan, and its cursor is the seq an interrupted run resumes from. [:aurora_meter, :replay, :phase] fires once for each of :announce, :drain, :compare and :activate; :announce carries seeded (rows copied into the building generation) and resumed, :drain carries drained, and :compare and :activate carry differences. A replay that finds differences under the default compare: :require_match emits :compare and no :activate, which is the shape a dashboard should alert on.

kind in the credits event is one of :grant, :hold, :settle, :release, :debit or :expire. duplicate: true marks an idempotent grant replay (with amount: 0); overrun: true marks a settlement above its hold.

tenant_key is metadata, never a metric tag: the cardinality is unbounded. The closed set of names a metric may tag on, the names it may never tag on and the reason for each are in Telemetry, and AuroraMeter.Telemetry.tag_allowed?/2 answers the question in code.

The flush span sits alongside the flat [:aurora_meter, :flush] event rather than replacing it: a host attached to the flat name is unaffected, and a host that wants flush latency attaches to [:aurora_meter, :flush, :stop]. An {:error, reason} from storage is :stop with result: :error; a raise is :exception. Both are followed by the unchanged [:aurora_meter, :flush, :error].

The two gauges are sampled every :metrics_interval inside AuroraMeter.Store and AuroraMeter.Cluster. No gauge event is emitted when metrics_interval is 0, and none is emitted for the cluster when cluster_sync is false. unreconciled_keys is omitted above :metrics_scan_ceiling rather than reported as zero.

7. PubSub messages

Message tags are covered by SemVer. Payload maps gain keys additively, so match on the keys you need rather than on the whole map.

The two cluster messages and the subscription invalidation are internal: they are how nodes talk to each other, not an API. Subscribe to the tenant topic and the credits topic; leave the other two alone.

What value in the usage message means. It is this node's converged view at the moment of the tick, and it includes units this node has reserved but not yet committed through reserve/3 or with_quota/4. With cluster_sync: true (the default) the message is node-local, so a browser connected to node B never sees node A's slightly different number.

8. Mix tasks

9. Migration entry points

The schema-version contract: a host calls these from its own Ecto migration. Versions are additive during 1.x. AuroraMeter.Migration.V1 to V8 are implementation modules and are internal (section 11).

Core schema version 8 is the one version that cannot share a host migration file with any other: it creates a unique index CONCURRENTLY, which Postgres refuses inside a transaction block. mix aurora_meter.gen.migration emits it as its own file, and up/1 raises AuroraMeter.Migration.ConcurrentVersionError rather than let it run halfway. A fresh install passes concurrently: false and builds the index inside the transaction, which is right for a table with no rows in it.

10. Test helpers

Supported, and shipped in the Hex tarball, so a host test suite may depend on them. They are governed by the test-helper heading of the support policy rather than by SemVer on every name, and nothing in production should call them.

use AuroraMeter.StorageCase, adapter: MyApp.Storage runs the adapter conformance suite against a custom AuroraMeter.Storage implementation; see Storage adapters.

use AuroraMeter.Test in an ExUnit.CaseTemplate installs the checkout and reset callbacks; see Testing.

11. Internal modules

These are compiled, public in the Erlang sense, and documented so the guides and the ADRs can link to them. They are not part of the supported surface. Each that renders a page carries a stability banner at the top of its module docs and appears under the "Internal" group in the generated documentation; the AuroraMeter.Bench.* modules carry @moduledoc false instead and render no page at all, because they are the benchmark's own machinery rather than anything a guide links to. They are listed here for the same reason as the rest: a boundary you cannot name is not a boundary.

The inventory test holds this list as a module attribute and fails when a module on it appears anywhere in the tables above, and when this list and the groups_for_modules "Internal" group in mix.exs disagree.

A function carrying @doc false inside any module is internal for the same reason, whether or not its module is on this list. The inventory test refuses to let one appear in the tables above.

12. Consumed by Aurora Meter Pro

Aurora Meter Pro is built on exactly this public surface and nothing else. The boundary is fixed in the V1 programme's free-pro-boundary.md section 2; it is restated here because it is part of what this page promises. Pro may use:

• the facade: usage/2, usage_all/1, history/3, period/1, plan/1, quota/2, check/2, entitled?/2, feature_value/3
• AuroraMeter.Storage dispatchers: load_counter/3, get_subscription/1, put_subscription/1, load_history_range/4, stream_counters/1
• everything in AuroraMeter.Credits and AuroraMeter.Credits.Money
• AuroraMeter.Plans.get/1, AuroraMeter.Plan
• AuroraMeter.Subscriptions.get/1 and invalidate/1
• AuroraMeter.Period.current!/2 and containing/2, AuroraMeter.Clock.now/0
• AuroraMeter.Flusher.flush/0, AuroraMeter.Test
• the behaviours AuroraMeter.Billing.Provider and AuroraMeter.Period

Anything else in the core is internal to Pro as well, even where it is currently public. Pro still reaches a handful of core tables directly; those accesses are recorded in Pro's own inventory as internal coupling scheduled for removal, and this page does not bless them.

This section names no Pro module, because the core never depends on Pro.