toposcope

The same hunt. Your disk.

Four files from the v0.5.2 release. ClickHouse and one Bun app. Same hunt as hosted.

$docker compose up -d
→ 127.0.0.1:8080

2 CPU · 4 GB RAM · 20 GB disk · Docker 24+

Single local login; no SSO or roles; no clustered ClickHouse.

Hosted waitlist →

Compose, then search.

Packaged stack on :8080. Wait for /api/health 200. Or ClickHouse in Docker and bun run dev.

Packaged
cp env.example .env
docker compose up -d
curl -fsS http://127.0.0.1:8080/api/health

Four files from the v0.5.2 release: compose.yml, env.example, vector.yaml, LICENSE. Image pin ghcr.io/toposcope/toposcope:0.5.2, published for amd64 and arm64. Set the three secrets in .env. Health is 503 with phase until 200, and carries the running version.

Develop
cp .env.example .env
docker compose -f compose.dev.yml up -d clickhouse
bun run dev # :5173, HMR

Clone the repo. ClickHouse in Docker. API on :8080, syslog on :5514. .env.example stays dotted; GitHub Releases rename it to env.example.

v0.5.2 release ↗skill for a coding agent: stand it up, check an error arrives ↗
vector -c vector.yamlThree smoke events, then it stays up as a collector: OTLP in on 4318 and 4317, a disk buffer in VECTOR_DATA_DIR. Vector 0.51 or newer. Search service:smoke.
bun run seedA small local dataset for bun run dev.
bun test · bun run e2eUnit and end-to-end checks against a running API.
bun run truncateEmpties logs, metrics, marks and the minute rollups — not SQLite.

Retention, tokens, backups — yours.

Account settings elsewhere are an endpoint or a volume here.

Before anything reaches the box: set your own TOPOSCOPE_PASSWORD, TOPOSCOPE_INGEST_TOKEN and CLICKHOUSE_PASSWORD — the packaged build refuses to boot on missing or demo secrets. Auth covers everything except GET /api/health and GET /api/metrics, which are localhost-bound.
PUT /api/settings{"retention_days": 30} — 1 to 365, ClickHouse TTL on the day partition. Old partitions age out; history is not rewritten by hand.
POST /api/api-tokensA named ingest token, shown once. One per collector: revoke Vector without taking down syslog.
POST /v1/marksA deploy, flag, incident or note on the same bearer token. Search / Follow draw it on the hunt histogram. Same id without end_ts is a skip; end_ts closes an open mark. GET /api/marks lists them.
POST /v1/probesA status check on the same bearer token: attach { service, up: 0|1 } or pull one status URL. A failed pull stores up=0. GET /api/probes lists samples; the hunt overlays up.
127.0.0.1:4319OTLP over gRPC, bound to localhost like :8080. OTLP_GRPC_PORT moves it; 0 turns it off. HTTP/2 without TLS: behind a reverse proxy it needs a rule of its own.
MemoryPlan about 2 GB for an idle instance, nearly all of it ClickHouse: 1.7 GiB measured fifteen minutes after start, on 0.4.10. Compose caps ClickHouse at 4 GB and the app at 512 MB.
docker volume ch_dataEvery event and change mark. Stop the stack, tar the volume. The README has the one-liner.
app_data / toposcope.sqliteSaved searches, tokens, alert rules and settings.
GET /api/metricsPrometheus text, unauthenticated, localhost-bound.
BootListens first. GET /api/health is 503 with phase (starting / schema / repair / ready) until ingest and search are safe, then 200. Rollups and new columns create and backfill per day.

New version tonight, old version back in a minute.

Compose pins the tag. The two volumes outlive the app. Upgrade is pull && up; rollback is one edit.

UPGRADEdocker compose pull && docker compose up -d
Compose pins an exact tag, never :latest. On stop the app finishes the requests in flight, then exits.
ROLL BACKpin the previous tag in compose.yml · up -d
One edit. The data directory outlives the app version.
BACK UPstop the stack · tar toposcope_ch_data + toposcope_app_data
Two volumes: every event and mark, and every saved search, token and alert.
RESTOREuntar into the volume paths · up -d
A data dir that will not start needs a restore, not a rollback. Practice it once.

v0.5

Shipped

Search, counted facets, traces, profiles, alerts. OTLP over HTTP and gRPC: logs, traces, profiles, and metrics as gauges, counters and histograms. Syslog. e1 fingerprints, on the log row and on the span that recorded the exception. Change marks on the hunt histogram. Around a mark: fingerprints, and compare per plotted level, service or host, on the same equal windows. service.version stored as version. Status checks, attached or pulled. Saved views, field catalog, tabs.

Not included

SSO, users and roles. Clustered ClickHouse. PromQL and metric-threshold alerts.

The repo is the product.

GitHub ↗Operations ↗