Skip to content
BEACON
Edge telemetry DBSingle binary71/71 tests · 0 clippy warnings

The 2.89MB time-series engine for edge & IoT.

Beacon is a single-binary Rust TSDB: Gorilla compression, a crash-safe write-ahead log, real-time SSE streaming, and a zero-dependency dashboard compiled straight into the executable. One process, one file, no sidecars.

cargo install --git https://github.com/prxmel4/beacon
beacon serve --port 8086 --data-dir ./beacon-data
git clone https://github.com/prxmel4/beacon.git && cd beacon
cargo build --release
./target/release/beacon serve --port 8086 --data-dir ./beacon-data
Read the docs View on GitHub No npm · no CDN · air-gapped LANs
GET /
35.1 KB · 0 assets
Beacon dashboard: KPI strip with point counts and compression ratio, a 60fps canvas chart of live temperature telemetry with a crosshair tooltip, and a monospace ingest ticker.
Live canvas · crosshair tooltip · mock sensorCompiled in via include_str!
Verified benchmarks

Measured on this repository, not a slide deck.

beacon bench --points 1000000 · release build · 24 series · 200 queries

Ingest throughput01
608,049pts/sec

Sustained ingest with WAL fsync and Gorilla flush included.

1,000,000 points · 24 series
Compression02
10.44×

Gorilla DoD + XOR: 1.53 B/point on disk vs 16 raw.

gorilla dod + xor
Query latency03
52.1µs

200 random 1%-window aggregations · p50 26 µs · p99 71 µs.

block-skip index
Binary size04
2.89MB

Static binary + 35.1 KB embedded UI. No runtime, no assets.

cargo build --release

Throughput varies ±10% between runs — 552K / 608K / 615K pts/sec across three runs, fsync-bound on the host disk.

Full-scan count over 333,334 points: 4.47 ms

Architecture

One process, from write-ahead durability to a 60fps canvas.

No external services · no message bus · no sidecars · no GC pauses

WRITE PATH · DURABLE ON ACKREAD PATH · ON-DEMAND DECODE01IoT / HTTPline protocolPOST /api/v1/write02WALcrc32 framedfsync before ack03MemTablesorted, in RAMflush @ 1000 pts04Segmentgorilla dod + xor1.53 B / point05Query / SSEblock-skip indexbroadcast · 102406Dashboard60fps canvas35.1 KB embedded
Write order01

compress → append → fsync → truncate WAL

The WAL is only cleared after the segment is durable.

Crash window02

replay + timestamp dedup

A crash between fsync and truncate replays already-flushed points.

Guarantee03

no acknowledged write is lost

Only an unacknowledged tail can be discarded.

Core capabilities

Everything an edge deployment needs. Nothing it doesn't.

Zero runtime dependencies in the shipped binary

Gorilla compression

01

Delta-of-delta timestamps plus XOR-encoded floats, bit-packed by a hand-written writer. Sixteen bytes of raw point becomes 1.53 B on disk.

dod + xor · 10.44×

Crash-safe WAL

02

Every acknowledged write is CRC32-framed and fsynced before the response. A torn tail is detected and truncated on startup, and replay is idempotent by timestamp.

crc32 · fsync before ack

Air-gap ready UI

03

The dashboard is a 35.1 KB document compiled into the binary. No CDN, no npm, no web fonts — it renders on a LAN with no route to the internet.

include_str! · --no-ui

Zero-panic core

04

71 tests, 0 clippy warnings, 0 unsafe blocks in the codec and storage paths. Protocol errors come back as typed JSON carrying the offending line number.

71/71 tests · 0 clippy

Line protocol

05

InfluxDB-compatible ingestion: multi-field writes, escaped keys, integer/unsigned/boolean suffixes, comment lines and multi-line batches validated atomically.

POST /api/v1/write

Real-time SSE

06

A bounded broadcast channel fans parsed points out to browsers. Slow subscribers get a lagged notice and resync instead of back-pressuring ingest.

GET /api/v1/stream
Quickstart

Zero to telemetry in three steps.

Rust toolchain or a prebuilt binary · Windows, Linux, macOS

  1. 01

    Install or build

    One Cargo command gets you running. Source builds need Rust 1.85+from rustup.rs; prebuilt binaries are on the Releases page if you would rather skip the toolchain.

    cargo · rustup.rs · releases
    Shell
    # prereq: Rust 1.85+ (https://rustup.rs)
    cargo install --git https://github.com/prxmel4/beacon
    
    # or build it yourself
    git clone https://github.com/prxmel4/beacon.git && cd beacon
    cargo build --release
  2. 02

    Launch & open console

    Start the server, open http://127.0.0.1:8086, then press MOCK SENSOR in the top bar to watch live 60fps telemetry appear immediately.

    dashboard · embedded · 60fps
    Shell
    beacon serve --port 8086 --data-dir ./beacon-data
    
    # from a source build:
    #   Windows        .\target\release\beacon.exe serve ...
    #   Linux / macOS  ./target/release/beacon serve ...
  3. 03

    Send real data

    Write line protocol to POST /api/v1/write from a shell, PowerShell script or ESP32 — then read it back withGET /api/v1/query. Timestamps are optional.

    write · query · stream
    Endpoints
    # single point
    curl -sS -X POST http://127.0.0.1:8086/api/v1/write \
      --data-binary 'cpu,device=edge-07,room=lab value=41.5 1732250000000'
    
    # raw range query
    curl -sS 'http://127.0.0.1:8086/api/v1/query?metric=cpu&from=1732250000000&to=1732250060000'
    
    # live SSE frames (Ctrl+C to stop)
    curl -sN 'http://127.0.0.1:8086/api/v1/stream'
    Endpoints
    # write a batch (timestamps are Unix milliseconds)
    $body = @"
    temperature,device=sensor-01,room=kitchen value=28.5 1732250000000
    humidity,device=sensor-01 value=61i 1732250000000
    "@
    Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8086/api/v1/write -Body $body
    
    # tag-filtered average over the whole series
    Invoke-RestMethod "http://127.0.0.1:8086/api/v1/query?metric=temperature&tag=device=sensor-01&agg=avg"
    
    Invoke-RestMethod "http://127.0.0.1:8086/api/v1/stats"
    Endpoints
    #include <WiFi.h>
    #include <HTTPClient.h>
    #include <time.h>
    
    const char* BEACON = "http://192.168.1.50:8086/api/v1/write";
    
    void sendSample(float tempC) {
      if (WiFi.status() != WL_CONNECTED) return;
    
      // Beacon timestamps are Unix milliseconds; omit it and the server uses now().
      long long ts = (long long)time(nullptr) * 1000LL;
      String line = "temperature,device=esp32-01,room=lab value="
                  + String(tempC, 2) + " " + String(ts);
    
      HTTPClient http;
      http.begin(BEACON);
      http.addHeader("Content-Type", "text/plain");
      int code = http.POST(line);   // 200 -> {"points_written":1}
      http.end();
    }

    Tabs are pure CSS (radio inputs + sibling selectors) — no framework, no hydration, no layout shift. The whole site ships as static HTML.