Cloudflare Worker (Hono) that serves the public Snake leaderboard for
sentry games leaderboard.
The leaderboard is a working example of Sentry application metrics: the CLI emits a metric with the SDK, and the Worker reads it back through the Events API. It has no database of its own.
sentry games snake Sentry (org sentry, CLI project) this Worker sentry games leaderboard
────────────────── ──────────────────────────────── ─────────── ────────────────────────
game over
→ reportSnakeScore(score) ───► `snake.score` distribution metric ◄── GET /api/0/organizations/ ◄── GET /v1/snake/leaderboard
(only when telemetry is on) tagged with `handle` sentry/events/ (read token) prints RANK, PLAYER, SCORE
→ top 10, cached for 5 min
- Write. When a run ends,
packages/cli/src/lib/games/score.tssends onesnake.scoremetric through the CLI's own Sentry SDK. It carries only the random player handle frompackages/cli/src/lib/games/player.ts.scrubAnonymousMetricinpackages/cli/src/lib/telemetry.tsdrops every other attribute. Nothing is sent when telemetry is off. - Read.
src/leaderboard.tsqueries thetracemetricsdataset for the highest score per handle over 30 days, validates every row, and keeps the top 10. The Workers Cache API holds the result for 5 minutes, and a rate limiter allows 30 requests per minute per IP. The limiter fails open. - Show.
packages/cli/src/lib/games/leaderboard-api.tsfetchesGET /v1/snake/leaderboardand validates it again.packages/cli/src/commands/games/leaderboard.tsmarks your own row.
GET https://games.sentry.new/v1/snake/leaderboard
{
"period": "30d",
"entries": [{ "rank": 1, "handle": "brave-otter-4242", "score": 57 }]
}Every other path returns 404 {"error":"Not found"}. Errors are 429
(rate limited), 502 (Sentry query failed), and 503 (no token). The Worker
reports 502 and 503 causes to Sentry when SENTRY_DSN is set. These
reports do not include the client IP, headers, cookies, bodies, or query
strings.
| Change | Where |
|---|---|
| Window, size, cache lifetime | Constants at the top of src/leaderboard.ts (LEADERBOARD_PERIOD, LEADERBOARD_SIZE, ...) |
| Handle format or score limit | packages/toolkit-core/src/games.ts, which the CLI and the Worker share |
| Metric name or attributes | packages/toolkit-core/src/games.ts, and scrubAnonymousMetric in telemetry.ts |
| Table the CLI prints | packages/cli/src/commands/games/leaderboard.ts |
| A new game | A new metric in the CLI and a new route in src/app.ts |
pnpm --filter @sentry/games-api run test
pnpm --filter @sentry/games-api run dev # then SENTRY_GAMES_API_URL=http://localhost:8787The Worker runs on a custom domain because the Cache API is a no-op on workers.dev.
The CLI team owns this Worker. It runs as sentry-games-api on the
Sentry Internal Cloudflare account, which also holds the sentry.new
zone.
The Deploy Games API GitHub Actions workflow deploys it after a successful
Test push run for the current main commit. It uses the production
environment with its own secrets, because the MCP Workers use a different
Cloudflare account:
GAMES_API_CLOUDFLARE_API_TOKEN: a Cloudflare API token for the Sentry Internal account with Workers Scripts: Edit and, for the custom domain, Workers Routes: Edit on thesentry.newzone.GAMES_API_CLOUDFLARE_ACCOUNT_ID: the Sentry Internal account ID.
The workflow keeps runtime variables and secrets (--keep-vars) and then
requests the public endpoint until it returns 200. Set the runtime secrets
once with Wrangler:
cd apps/games-api
CLOUDFLARE_ACCOUNT_ID=<Sentry Internal account ID> npx wrangler secret put SENTRY_GAMES_READ_TOKEN
CLOUDFLARE_ACCOUNT_ID=<Sentry Internal account ID> npx wrangler secret put SENTRY_DSN- A Sentry token with only the
org:readscope. - The token's user must be a member only of the team that owns the CLI project.
- Enable "Prevent storing IP addresses" on that project.