analytics
@rtorcato/cf-common/analytics wraps the Analytics Engine binding's
writeDataPoint(). A data point is three positional arrays (blobs,
doubles, indexes), and queries read them back as blob1, double1,
index1. createDataset names those slots once, so you write and query by name.
import { createDataset, writeDataPoint } from '@rtorcato/cf-common/analytics'
import { getBinding } from '@rtorcato/cf-common/env'
const events = getBinding<AnalyticsEngineDataset>(env, 'REQUESTS')
Bind it
Add a dataset to your wrangler config. The dataset is created on the first write:
{
"analytics_engine_datasets": [{ "binding": "REQUESTS", "dataset": "requests" }]
}
Write by name
Declare the columns in slot order. blobs are strings (or bytes), doubles
are numbers, and index is the one sampling key (a customer or tenant id is
typical):
const requests = createDataset(events, {
blobs: ['path', 'country'],
doubles: ['latencyMs', 'status'],
index: 'customerId',
})
requests.write({
path: url.pathname,
country: request.cf?.country ?? null,
latencyMs: Date.now() - start,
status: response.status,
customerId,
})
Field names and types are checked at compile time: an unknown column, a
missing double or index, or a string in a double slot fails to build. A blob
you leave out is written as null.
Only append to a schema. The names map to positions, so reordering or removing a column writes new data into a slot that holds a different column in older rows.
Query by name
columns maps each name to the column the SQL API reads:
const { path, latencyMs } = requests.columns // 'blob1', 'double1'
const sql = `
SELECT ${path} AS path, avg(${latencyMs}) AS latency
FROM requests
WHERE timestamp > NOW() - INTERVAL '1' DAY
GROUP BY path`
Send it to the
SQL API
with an API token that has Account Analytics read access. Analytics Engine
samples at high volume, so weight counts and sums by _sample_interval.
Write positionally
writeDataPoint takes the binding's own shape, for one-off writes or a
dataset you don't want to name:
writeDataPoint(events, { blobs: ['/api'], doubles: [12], indexes: ['c_1'] })
When the write fails
writeDataPoint is fire-and-forget: it returns void and never waits on the
network. A point may hold at most 20 blobs, 20 doubles and one index of up to
96 bytes, with blobs under 16 KB in total. If the binding throws on a point,
the error becomes a CloudflareError with status 500, code
ANALYTICS_WRITE_FAILED and the original error as cause. That is a bug in
the point, not a client error, so the message is not exposed. See errors for how to catch it.
Good to know
- A Worker invocation can write up to 250 data points.
- A missing
REQUESTSbinding is a deploy misconfiguration.getBindingthrows a non-exposed500for it, the same as the other bindings. - See the Analytics Engine limits for the current numbers.
See the analytics API reference for the full signatures.