Metering events

Objective

Metering is a platform convention rather than an implementation detail of Billing, because usage history cannot be reconstructed after the fact. Anything not recorded correctly on the first day cannot be billed for later and cannot be defended in a dispute.

Read this page before any service emits its first usage record.

Requirements

None

Instructions

The record

Every billable thing emits usage records containing at least:

Field	Type	Meaning
`RecordId`	string	Unique; the deduplication key
`AccountId`	string	Who is billed
`ResourceArn`	string	What was used
`Region`	string	Where, stated rather than parsed out of the ARN
`MeterName`	string	Which meter, from a fixed vocabulary
`Quantity`	integer	How much; may be negative on a correction
`Unit`	string	The unit of the quantity
`StartTime`	timestamp	Inclusive
`EndTime`	timestamp	Exclusive
`PriceVersion`	string	Which catalogue version applied
`CorrectsRecordId`	string	Present only on a correcting record

Region is carried explicitly rather than derived from the ARN. Global services have an empty region segment in their ARNs, and parsing an identifier to recover billing information contradicts the rule that identifiers are opaque.

PriceVersion exists so that an invoice can be recomputed and defended after a price change. Without it, an old invoice cannot be reproduced from its inputs.

Interval semantics

The interval is half-open: [StartTime, EndTime). The start instant is included; the end instant is not.

Consecutive records for one resource therefore abut exactly. No second is counted twice, and no second is lost, at every boundary between every pair of records. Left ambiguous, two engineers would choose differently and the error would be systematic across millions of records rather than occasional.

When a record is written

A record is written for the interval in which the usage occurred, as it occurs — not at creation of the resource, and not when the invoice is prepared.

A resource that exists over time produces a series of records covering that time. A single record written at creation could not express a duration, and nothing that is billed by elapsed time could be invoiced at all.

An idempotent API replay creates no new resource and therefore opens no second series of records.

Resolution

PROPOSED: usage is recorded at one-second resolution.

Recording is deliberately finer than charging: the charging rule can then be stated exactly rather than approximated, and a finer record can always be aggregated while a coarser one can never be refined.

OPEN (Michael): the charged granularity, and the rounding rule for a partial unit — what is rounded, at which step, and in which direction. It must appear both here and in the Billing user guide, because a customer reconciling an invoice needs it.

The clock

Usage timestamps come from the platform, not from inside a customer’s instance, so that a clock set wrongly inside an instance cannot affect what is charged.

OPEN (Michael): which component is authoritative, and what happens to records from a host whose clock is found to be wrong. The 15-minute skew tolerance that applies to API requests does not apply here: in metering, a clock error is money.

Meters

The meter vocabulary is fixed and versioned like an API. A meter name is never reused for a different measurement, and a meter whose definition must change gets a new name.

OPEN (Michael): the v1 meter vocabulary.

Corrections

Records are immutable. A record found to be wrong is never edited.

A correction is a new record that names the record it corrects in CorrectsRecordId and carries the difference in Quantity, which may be negative.

The total usage of a resource is therefore the sum of its records, corrections included, and the history of what was believed at each point remains readable. Without the linking field, a correction is indistinguishable from additional usage and an invoice cannot be explained line by line.

Retention

OPEN (Michael): how long raw usage records are retained. This is a legal question as much as a technical one and belongs in the terms as well as here.

Note that request logs are proposed at 90 days. If usage records are retained for longer — and tax law will require that they are — a dispute about an old period can be resolved from usage records but not from request logs. That is acceptable, but it should be a decision rather than a surprise.

Egress

Egress is recorded and is not charged for.

The distinction is the whole point. Not charging is a product commitment, and it can be revisited by a future release without breaking anything. Not recording would be irreversible: no history to bill from later, and no visibility of abuse until it arrives as an invoice from an upstream transit provider.

So egress produces usage records like everything else. No egress line appears on any invoice.

OPEN (Michael): confirmation that egress metering is built in v1 even though nothing is charged for it.