This library offers some low level building blocks to record and analyze custom events in Redis. It's main purpose is to provide a simple way to record and query events in Redis without having to worry about the underlying data structure so we can build more advanced analytics features on top of it.
Quickstart
- Create a redis database
Go to console.upstash.com/redis and create a new global database.
After creating the db, copy the UPSTASH_REDIS_REST_URL
and UPSTASH_REDIS_REST_TOKEN
to your .env
file.
- Install
@upstash/analytics
in your project
npm install @upstash/analytics @upstash/redis
- Create an analytics client
import { Analytyics } from "@upstash/analytics";
import { Redis } from "@upstash/redis";
const analytics = new Analytics({
redis: Redis.fromEnv(),
window: "1d",
});
- Ingest some events
An event consists of a time
field and any additional key-value pairs that you can use to record any information you want.
const event = {
time: Date.now() // optional (default: Date.now())
userId: "softquantus",
page: "/auth/login",
country: "DE",
}
await analytics.ingest("pageviews", event);
- Query your events
const result = await analytics.query("pageviews");
Development
This project uses pnpm
for dependency management.
Install dependencies
pnpm install
Build
pnpm build
Database Schema
All metrics are stored in Redis Hash
data types and sharded into buckets based on the window
option.
@upstash/analytics:{TABLE}:{TIMESTAMP}
TABLE
is a namespace to group events together. ie for managing multiple projects int a single databaseTIMESTAMP
is the starting timestamp of each window
The field of each hash is a serialized JSON object with the user's event data and the value is the number of times this event has been recorded.
{
'{"page": "/auth/login","country": "DE"}': 5,
'{"page": "/auth/login","country": "US"}': 2
}