Documentation

01Quick start

TinyObs is one Go binary with an embedded store. There is nothing else to run. The dashboard and API both listen on port 8080.

git clone https://github.com/nicktill/tinyobs && cd tinyobs
docker compose up -d

go run ./cmd/server

To generate demo traffic, run the example app with go run ./cmd/example or make docker-demo, then open http://localhost:8080.

02Instrument an app

The Go SDK batches samples and pushes them every few seconds. The HTTP middleware records http_requests_total and http_request_duration_seconds, labelled by the route pattern your ServeMux matched, so IDs in URLs never become new series.

client, _ := sdk.New(sdk.ClientConfig{
    Service:  "my-app",
    Endpoint: "http://localhost:8080/v1/ingest",
})
client.Start(ctx)
defer client.Stop()

mux := http.NewServeMux()
mux.HandleFunc("GET /users/{id}", getUser)
handler := httpx.Middleware(client)(mux)  // path="/users/{id}"

errors := client.Counter("errors_total")
errors.Inc("type", "api_error")

03Remote write

Anything that speaks Prometheus remote write 1.0 can push to TinyObs: Prometheus, Grafana Alloy, the OpenTelemetry Collector, vmagent.

remote_write:
  - url: http://localhost:8080/api/v1/write

If TINYOBS_AUTH_TOKEN is set, add authorization: { credentials: <token> } to the entry. The Go SDK sends it from ClientConfig.APIKey.

Samples that can never be stored (out of order, over a series limit, invalid labels) get a 400, so senders drop them instead of retrying forever. Storage errors get a 5xx and are retried.

04PromQL

The engine runs Prometheus's own promqltest suite (make promql-compat). A supported feature returns what Prometheus returns. Anything else is an explicit “not supported” error, never a guess.

curl -s localhost:8080/api/v1/query \
  --data-urlencode 'query=histogram_quantile(0.99, sum by (le) (rate(http_request_duration_seconds_bucket[5m])))'

05HTTP API

Request parameters, response shapes and error types follow the Prometheus HTTP API.

06Configuration

Configured with environment variables. Invalid values stop the server at startup rather than falling back to a default.

07Cardinality & retention

Every unique label set is a series, and series are what cost memory and disk. TinyObs caps them twice. The global limit bounds the whole server. The per-metric limit stops one runaway label, such as a user ID, from using up the global budget for every other metric.

Pushed series have no scrape to fail. When a service stops, its series keep their last value for the 5-minute lookback window, then drop out of instant queries.

Retention is time-based and runs hourly, without pausing ingestion. Disk use is predictable:

disk ≈ series × samples per series in the window × ~14 bytes

# 5,000 series, 15s interval, 72h retention
5,000 × 17,280 × 14 B ≈ 1.2 GB

Rejected samples are never dropped silently. Alert on the counter, and use the status endpoint to find the metric responsible:

curl -s localhost:8080/metrics | grep -E 'tinyobs_(series|samples_rejected)'
curl -s localhost:8080/api/v1/status/tsdb | jq '.data.seriesCountByMetricName'

08Grafana

Add a Prometheus data source with the URL http://localhost:8080 (from a container, http://host.docker.internal:8080). Existing dashboards work, as long as their queries stay within the supported PromQL above.