Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
39 commits
Select commit Hold shift + click to select a range
1b52095
chore: remove the Go UDP prototype and its deploy pipeline
itsdangold Aug 20, 2026
5ac3b4c
build: scaffold the React + TypeScript + Vite app
itsdangold Aug 20, 2026
0f7f0bd
feat(data): event model, ring buffer and pluggable sources
itsdangold Aug 20, 2026
6973f72
feat(data): land mask baked from Natural Earth
itsdangold Aug 20, 2026
c8d9e9d
feat(data): synthetic event generator weighted by population
itsdangold Aug 20, 2026
e543e8e
feat(style): one schema for every visual parameter
itsdangold Aug 20, 2026
54f1390
feat(render): scene, globe surface and starfield
itsdangold Aug 20, 2026
c29e8d5
feat(render): event beams as ribbons, bars and sprites
itsdangold Aug 20, 2026
586911a
feat(render): procedural cloud layer, soft and voxel
itsdangold Aug 20, 2026
dcb0748
feat(render): post FX chain with map-only chromatic aberration
itsdangold Aug 20, 2026
f5604ae
feat(ui): CRT chrome and SDK leaderboard
itsdangold Aug 20, 2026
8c9414c
feat(dev): live style panel behind D
itsdangold Aug 20, 2026
3bc440f
feat(dev): performance HUD behind M
itsdangold Aug 20, 2026
86bfda6
feat: wire the app together
itsdangold Aug 20, 2026
0de731b
docs: reference for every style control
itsdangold Aug 20, 2026
5de5eab
fix(render): seat beams on the globe instead of a fixed radius
itsdangold Aug 20, 2026
d65d3e1
feat(render): hold beams at full height for a set delay before they r…
itsdangold Aug 20, 2026
a8ca654
feat(render): beam timing is grow + hold + shrink, all in seconds
itsdangold Aug 20, 2026
f0f88a9
feat(render): clouds can grow far wider, and wrap the globe as they do
itsdangold Aug 20, 2026
b97da23
feat(backend): a Go service that fans the UDP feed out over SSE
itsdangold Aug 21, 2026
067343f
feat(data): read the live feed, and pick a source without a restart
itsdangold Aug 21, 2026
59bfb53
fix(data): hold the synthetic rate to what the headline claims
itsdangold Aug 21, 2026
b9d9d5b
feat(data): region counts, a recent slice, and where each region sits
itsdangold Aug 21, 2026
169011e
feat(render): fit the globe to the viewport, and drop zoom
itsdangold Aug 21, 2026
6bb5cb0
chore(style): resave the CRT 2 preset in full
itsdangold Aug 21, 2026
f0941fc
refactor(dev): keep the style panel and the perf HUD out of the deplo…
itsdangold Aug 21, 2026
a7a2f76
feat(ui): rebuild the overlay as a character-cell TUI
itsdangold Aug 21, 2026
8912f5f
feat(ui): an alerts bulletin, derived from the stream itself
itsdangold Aug 21, 2026
1d263f1
feat(render): Seer, an easter egg in orbit
itsdangold Aug 21, 2026
2d500cc
perf(render): stop drawing and uploading what the frame does not use
itsdangold Aug 21, 2026
b4cfab8
feat(ui): a cold-start sequence that boots into the display
itsdangold Aug 21, 2026
39a5967
feat(ui): colour the readouts by what they are reporting
itsdangold Aug 21, 2026
c6301d0
fix(ui): keep the layout on screen at every width
itsdangold Aug 21, 2026
224e110
docs: a README for running the frontend and the live backend
itsdangold Aug 21, 2026
ef5a5e1
docs: cut the README back to getting started
itsdangold Aug 21, 2026
5cae4f4
build: ship this frontend through the existing deploy pipeline
itsdangold Aug 21, 2026
505a660
fix(ui): report the feed a production build is actually on
itsdangold Aug 21, 2026
0dc94a8
Merge master into hackweek-2026
itsdangold Aug 21, 2026
6383bca
fix(render): apply the additive switch to the line style too
itsdangold Aug 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -1,4 +1,11 @@
.git/
.github/
.claude/
gocd/
node_modules/
dist/
static/
.dockerignore
LICENSE
README.md
SETTINGS.md
8 changes: 6 additions & 2 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,12 @@ jobs:
[ "$HEALTH" = "ok" ] || (echo "healthz returned: $HEALTH" && exit 1)
# /stats must return ingest counters JSON
curl -sf http://localhost:7000/stats | grep -q 'udp_received' || (echo "stats missing udp_received" && exit 1)
# / must return 200 and contain the frontend
curl -sf http://localhost:7000/ | grep -q 'Sentry Live' || (echo "index page missing expected content" && exit 1)
# / must return 200 and be the built frontend, not a bare index:
# the asset it names has to be in the image and served too.
curl -sf http://localhost:7000/ | grep -q '<title>Orbital</title>' || (echo "index page missing expected content" && exit 1)
ASSET=$(curl -sf http://localhost:7000/ | grep -o '/assets/index-[^"]*\.js' | head -1)
[ -n "$ASSET" ] || (echo "index page names no built bundle" && exit 1)
curl -sfI "http://localhost:7000$ASSET" > /dev/null || (echo "bundle $ASSET not served" && exit 1)
docker stop orbital-smoke

- name: Push to GHCR
Expand Down
13 changes: 6 additions & 7 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
orbital
orbital_bin

# Frontend build output (generated by Vite)
node_modules/
dist/
static/
.DS_Store
*.log

# Frontend dependencies
frontend/node_modules/

# Local tooling state (machine-specific paths, personal permission allowlists)
.claude/
30 changes: 18 additions & 12 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -1,23 +1,29 @@
# Stage 1: Build frontend with Bun
FROM oven/bun:1 AS frontend
# The image the live site runs: one static Go binary plus the built frontend.
#
# The frontend lives at the repo root (it used to be under frontend/, built with
# bun), so stage 1 builds from the root with npm. Vite writes to `static/`
# because that is the directory main.go serves — see vite.config.ts.

# Stage 1: Build frontend
FROM node:22-alpine AS frontend
WORKDIR /app
COPY frontend/package.json frontend/bun.lock* ./
RUN bun install --frozen-lockfile
COPY frontend/ .
RUN bun run build
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

# Stage 2: Build Go binary
FROM golang:1.25-alpine AS builder
RUN mkdir -p /usr/src/orbital
COPY . /usr/src/orbital
COPY --from=frontend /static /usr/src/orbital/static
WORKDIR /usr/src/orbital
RUN CGO_ENABLED=0 go build -ldflags '-extldflags "-static"' -v ./...
COPY go.mod go.sum ./
RUN go mod download
COPY main.go ./
RUN CGO_ENABLED=0 go build -ldflags '-extldflags "-static"' -o /bin/orbital .

# Stage 3: Runtime
FROM scratch
COPY --from=builder /usr/src/orbital/orbital /bin/
COPY --from=builder /usr/src/orbital/static/ /static/
COPY --from=builder /bin/orbital /bin/
COPY --from=frontend /app/static/ /static/

EXPOSE 7000
EXPOSE 5556/udp
Expand Down
128 changes: 77 additions & 51 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,80 +1,106 @@
# Orbital
# Sentry Orbital

Orbital is a geographical visualization of Sentry data — a real-time 3D globe showing error events as they happen worldwide.
A globe that draws a beam for every event, with a terminal overlay reading out
throughput, SDK families and regions.

## Architecture
## Run it

- **Go backend** (`main.go`): Receives UDP events, rate-limits them (~50/s max), and fans out via SSE to connected browsers
- **React frontend** (`frontend/`): Vite + React + TypeScript app using [cobe](https://github.com/shuding/cobe) for the WebGL globe

## Development

### Prerequisites
```bash
npm install
npm run dev
```

- Go 1.25+
- [Bun](https://bun.sh) (for the frontend)
<http://localhost:5190>. That is everything — it runs on synthetic data.

### Running locally
## Add the live feed

You'll need two terminal windows:
In a second terminal:

**Terminal 1 — Go backend with test events:**
```bash
go run main.go -test
npm run backend # Docker, nothing else to install
npm run backend:native # or natively, needs Go 1.25
```

This starts the backend on `:7000` with a test event generator that simulates real-world traffic.
Reload the page. It finds the backend and switches over on its own.

**Terminal 2 — Vite dev server:**
```bash
cd frontend
bun install
bun run dev
## Data source

`auto` in development: synthetic until a backend answers `/healthz`, then live.
It does not switch back if the stream drops.

Force one, dev only:

```
?source=synthetic ?source=real ?source=auto
```

This starts the Vite dev server on `:5173` with HMR. API requests (`/stream`, `/healthz`) are proxied to the Go backend.
or `VITE_EVENT_SOURCE=synthetic|real|auto` before `npm run dev`.

**Open http://localhost:5173** to see the live globe with test events.
A production build is hard-wired to the live feed — no override, and the
synthetic generator is not in the bundle.

### Production build
## Backend

```bash
cd frontend
bun run build # outputs to ../static/
cd ..
go run main.go -test
```
Serves `/stream` (SSE), `/healthz` and `/stats` on `:7010`. Vite proxies those
three paths.

`npm run backend:native` is `go run main.go`, so it takes any flag:

| flag | default | |
| --- | --- | --- |
| `-host` | `127.0.0.1` | listen address |
| `-http-port` | `7000` | HTTP port (npm scripts publish it on 7010) |
| `-udp-port` | `5556` | UDP port |
| `-test` | off | generate test events internally |
| `-sample-rate` | `1.0` | fraction of datagrams eligible to forward |
| `-max-forward-rate` | `50` | ceiling on events/sec sent to clients |

Open http://localhost:7000 to see the production build served by Go.
Both npm scripts pass `-test`. Port 7010 rather than 7000 because macOS AirPlay
squats on 7000; point the frontend elsewhere with
`ORBITAL_BACKEND=http://host:port npm run dev`.

## Docker
The Docker script publishes only the HTTP port. For a real producer sending
UDP, publish that too:

```bash
docker build -t sentry-orbital .
docker run --rm -p 7000:7000 -p 5556:5556/udp -e HOST=0.0.0.0 sentry-orbital
docker run --rm -p 7010:7000 -p 5556:5556/udp \
-v "$PWD":/src -w /src golang:1.25-alpine \
sh -c 'go run main.go -host 0.0.0.0'
```

## Configuration
## In the browser

| Flag | Default | Description |
|------|---------|-------------|
| `-host` | `127.0.0.1` | Listen address |
| `-http-port` | `7000` | HTTP port |
| `-udp-port` | `5556` | UDP port for event ingest |
| `-sample-rate` | `1.0` | Fraction of UDP events eligible to forward (0.0–1.0) |
| `-max-forward-rate` | `50` | Max events/sec forwarded to SSE clients (`0` = unlimited) |
| `-test` | `false` | Enable test event generator |
| | |
| --- | --- |
| `C` or `?dev` | style panel + diagnostics — localhost only |
| `F` | hide the readouts |
| `S` | mute |
| `?quality=low\|medium\|high` | force a rendering tier |

`/stats` exposes cumulative UDP `received` / `forwarded` / `dropped` counters for diagnosing ingest outages.
Every style control is documented in [SETTINGS.md](SETTINGS.md).

## UDP Event Format
## Build

Events are sent as JSON arrays:
```json
[37.8, -122.4, 1700000000000, "javascript"]
```bash
npm run build # -> dist/
npm run preview # serve it on :5190, still proxied to the backend
```
Format: `[latitude, longitude, timestamp_ms, platform]`

## License
> The container build does not work yet. `Dockerfile` expects the frontend under
> `frontend/` with output at `/static`; it is at the repo root and Vite emits
> `dist/`. The Go service serves `static/`, which nothing produces.

## Deploy

Push to `master` builds the image and deploys it — nothing here is run by hand.

- **GitHub Actions** (`.github/workflows/build.yml`) builds the Dockerfile, runs
a smoke test against the running container, and pushes
`ghcr.io/getsentry/sentry-orbital:{nightly,<sha>}`.
- **GoCD** (`gocd/`) waits for that check by name — *Build and smoke test* — and
rolls the image out to the `orbital` container in each US region.

Apache 2.0
The image is one static Go binary plus the built frontend: `npm run build`
writes to `static/`, which is the directory `main.go` serves. That is why the
build output is `static/` and not `dist/` — point it elsewhere and the container
serves nothing.
Loading
Loading