https://github.com/upstash/core-analytics
Low level analytics building blocks for redis
https://github.com/upstash/core-analytics
analytics edge redis serverless upstash upstash-sdk
Last synced: 5 days ago
JSON representation
Low level analytics building blocks for redis
- Host: GitHub
- URL: https://github.com/upstash/core-analytics
- Owner: upstash
- Created: 2023-02-09T08:20:09.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-07-19T09:54:35.000Z (12 months ago)
- Last Synced: 2025-06-05T22:38:37.485Z (25 days ago)
- Topics: analytics, edge, redis, serverless, upstash, upstash-sdk
- Language: TypeScript
- Homepage:
- Size: 487 KB
- Stars: 16
- Watchers: 7
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
@upstash/core-analytics
Serverless Analytics for Redis
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.
The quickstart below is slightly outdated. We're working on it.
## Quickstart
1. Create a redis database
Go to [console.upstash.com/redis](https://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.
3. Install `@upstash/core-analytics` in your project
```bash
npm install @upstash/analytics @upstash/redis
```
4. Create an analytics client
```ts
import { Analytics } from "@upstash/core-analytics";
import { Redis } from "@upstash/redis";
const analytics = new Analytics({
redis: Redis.fromEnv(),
window: "1d",
});
```
5. 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.
```ts
const event = {
time: Date.now() // optional (default: Date.now())
userId: "chronark",
page: "/auth/login",
country: "DE",
}
await analytics.ingest("pageviews", event);
```
4. Query your events
```ts
const result = await analytics.query("pageviews");
```
## Development
This project uses `bun` for dependency management.
#### Install dependencies
```bash
bun install
```
#### Build
```bash
bun 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 database
- `TIMESTAMP` 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.
```json
{
"{\"page\": \"/auth/login\",\"country\": \"DE\"}": 5,
"{\"page\": \"/auth/login\",\"country\": \"US\"}": 2
}
```