Use Cases
Background Jobs
Track asynchronous work, queue throughput, and job outcomes.
Use background job metering when product usage happens outside a request path: exports, imports, syncs, report generation, notifications, scheduled jobs, media processing, and automation runs.
Model
Create a meter such as background_jobs with:
| Field | Value |
|---|---|
| Unit | job |
| Aggregation | sum |
| Quantity | Usually 1 per completed or attempted job |
Useful dimensions:
queuestatusjob_typeworker_region
How To Use It
Record the job after it reaches the state you care about. Many products record both successful and failed jobs, then use the status dimension to separate billable work from operational reporting.
This lets you answer:
- How many jobs did each customer run?
- Which queues are busiest?
- Which job types fail most often?
- Which regions or workers process the most work?
Example
Create a job meter:
curl -X POST "$OPEN_SPANNER_BASE_URL/v1/meters" \
-H "Authorization: Bearer $OPEN_SPANNER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "background_jobs",
"description": "Background jobs attempted or completed",
"unit": "job",
"aggregation": "sum",
"event_retention_days": 90,
"dimensions": [
{ "name": "queue", "type": "string" },
{ "name": "status", "type": "string" },
{ "name": "job_type", "type": "string" },
{ "name": "worker_region", "type": "string" }
]
}'Record the job after it reaches the state you care about:
curl -X POST "$OPEN_SPANNER_BASE_URL/v1/usages" \
-H "Authorization: Bearer $OPEN_SPANNER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"idempotency_key": "job_export_789_completed",
"subject": "org_123",
"meter": "background_jobs",
"quantity": 1,
"metadata": {
"queue": "exports",
"status": "completed",
"job_type": "usage_export",
"worker_region": "us-east"
}
}'