Nunatak¶

Nunatak is a dashboard for the queries of many processes, which you run yourself. Your processes send it their queries while they run, with HttpEventExporter, and it shows:

Home: what changed in the last 24 hours. A query that got slower than usual, started failing, raised a new warning or got faster is listed with one sentence on why, such as a plan change; every other query is counted as running as usual. Queries running at this moment are shown against how long they usually take, and the side shows where the time went.
Queries: every query, grouped by label, with its time lately against its usual time, a trend, failures and warnings, those that need a look first. A second view shows each query day by day, to see when a change started.
A query: one label's runs on a chart, its plan versions with the nodes each one added or dropped, and every run against the usual time of its plan.
A run: one query as the profile viewer shows it, both plans with their counters and findings, and a replay from start to end, next to the usual time of its plan. A running query updates while you watch.

It is one program with no dependencies, and keeps everything in one folder on its machine.

Start it¶

Download the archive for your system from the releases whose tag starts with nunatak-v, for Linux (x86_64 and arm64) or macOS (Apple silicon), and run it:

$ tar -xzf nunatak-0.1.0-x86_64-unknown-linux-musl.tar.gz
$ ./nunatak

Or with Docker:

$ docker run -d --name nunatak -p 127.0.0.1:7766:7766 -v nunatak-data:/data ghcr.io/jan-krueger/nunatak:0.1.0
$ docker logs nunatak

When it starts, it prints where it is:

Nunatak 0.1.0

  Dashboard  http://127.0.0.1:7766
  Data       /home/me/nunatak-data
  Token      in /home/me/nunatak-data/token
  Keeps      every run

Send events from Python with:

    import polars_telemetry
    from polars_telemetry.export import HttpEventExporter
    polars_telemetry.install(exporter=HttpEventExporter("http://127.0.0.1:7766", token="3f9c..."))

On its first start it creates a token, the password processes send their events with, and prints it once. It stays in the token file of its data folder.

Send it queries¶

In the process whose queries you want to see:

import polars_telemetry
from polars_telemetry.export import HttpEventExporter

polars_telemetry.install(
    exporter=HttpEventExporter("http://127.0.0.1:7766", service="orders-etl", environment="prod")
)

with the token in the NUNATAK_TOKEN environment variable, or passed as token=. service and environment are what the dashboard filters by; the host is added for you. Name queries with labels so that runs of the same query are grouped together.

A query appears on Home once it has run for a second, and is kept when it ends. One that ends sooner appears when it ends. Sending happens on a background thread and never slows a query down; when Nunatak is away, the exporter keeps the events and sends them later, see Events over HTTP.

Add recordings you already have¶

Recordings written by the events exporter can be added to the history, compressed or not:

$ ./nunatak import profiles/events.jsonl.gz
Imported 1840 events from 1 files; 0 were already there, 0 queries had not finished.

Pass the same --data folder Nunatak runs with. A file imported twice adds nothing the second time.

Next¶

Running Nunatak: settings, sharing it with a team, keeping data, backups.
HTTP API: what it receives and how to read its history from your own scripts.