Meter Definition

A meter definition is the contract for one product signal. It tells Open Spanner which usage events are valid, what unit they represent, how values should be aggregated, and which metadata dimensions are accepted.

Common examples:

api_requests
storage_gb
export_jobs
seats

If your application sends usage for api_requests, Open Spanner looks up the api_requests meter before accepting the event.

Meter Fields

Field	Purpose
`name`	Stable API name clients send with usage events.
`description`	Human-readable business meaning shown in the dashboard.
`unit`	What the quantity represents.
`aggregation`	How events are summarized.
`event_retention_days`	How long raw events are retained.
`dimensions`	Dimension contract for accepted event metadata.

Meters can be created and updated from the dashboard or through the meter API. Keep name stable once clients are sending usage, because usage events reference meters by name.

Example Definition

{
  "name": "api_requests",
  "description": "API requests served",
  "unit": "request",
  "aggregation": "sum",
  "event_retention_days": 90,
  "dimensions": [
    { "name": "region", "type": "string", "required": true },
    { "name": "plan", "type": "string", "required": true },
    { "name": "cache_hit", "type": "boolean", "required": false }
  ]
}

Aggregation Modes

Open Spanner supports:

sum
count
avg
min
max
first
last
rate

Use sum for additive usage, count for event counts, avg, min, and max for sampled values, first or last for gauge-like values, and rate when you need event velocity over the requested window.

Meter Patterns

Open Spanner does not have separate meter classes for count, continuous, or seat-based meters today. Model those patterns with the meter's unit, aggregation mode, and event shape:

Pattern	Example meter	Suggested shape
Event count	`api_requests`	`unit=request`, `aggregation=sum`, `quantity=1` per accepted request.
Token or byte volume	`tokens`, `storage_bytes`	`unit=token` or `byte`, `aggregation=sum`, quantity from the completed operation.
Gauge-like state	`active_seats`	`unit=seat`, `aggregation=last`, quantity is the latest observed value.
Duration or utilization	`job_seconds`	`unit=second`, `aggregation=sum`, quantity is the measured duration.

Model Product Usage

Start with the thing your product needs to bill, limit, or report. Good meter names are stable, lowercase, and specific:

api_requests
tokens
storage_gb
workflow_runs

Use meter dimensions for context that changes per event, such as region, plan, or service. Dimension names can use letters, numbers, underscores, hyphens, and dots. subject is built in and does not need to be added as a meter dimension.

What Is Coming Later

Future versions may add richer meter types and dimension workflows. For now, the stable contract is the meter definition plus explicit dimensions, and that is the surface your services should depend on.