TimelessMetrics User’s Guide

This Livebook reflects the current default setup on main.

Install

defp deps do
  [
    {:timeless_metrics, "~> 6.0"}
  ]
end

Start a Store

Persisted store:

children = [
  {TimelessMetrics, name: :metrics, data_dir: "/tmp/metrics_data"},
  {TimelessMetrics.HTTP, store: :metrics, port: 8428}
]

Memory-only store:

children = [
  {TimelessMetrics, name: :metrics, mode: :memory},
  {TimelessMetrics.HTTP, store: :metrics, port: 8428}
]

The default engine is the Rust engine. You only need to set engine: if you are explicitly selecting the legacy path for compatibility work.

Common Store Options

These are the most relevant options for the current default path:

Write Data

Single point:

TimelessMetrics.write(:metrics, "cpu_usage", %{"host" => "web-1"}, 73.2)

Explicit timestamp:

TimelessMetrics.write(:metrics, "cpu_usage", %{"host" => "web-1"}, 68.5,
  timestamp: 1_700_000_000
)

Batch write:

TimelessMetrics.write_batch(:metrics, [
  {"cpu_usage", %{"host" => "web-1"}, 73.2},
  {"cpu_usage", %{"host" => "web-2"}, 61.8},
  {"mem_usage", %{"host" => "web-1"}, 4_200_000_000}
])

Query Data

Raw series:

{:ok, points} =
  TimelessMetrics.query(:metrics, "cpu_usage", %{"host" => "web-1"},
    from: System.os_time(:second) - 3600,
    to: System.os_time(:second)
  )

Multi-series query:

{:ok, results} =
  TimelessMetrics.query_multi(:metrics, "cpu_usage", %{"host" => "web-1"},
    from: System.os_time(:second) - 3600
  )

Aggregate query:

{:ok, buckets} =
  TimelessMetrics.query_aggregate(:metrics, "cpu_usage", %{"host" => "web-1"},
    from: System.os_time(:second) - 3600,
    bucket: {60, :seconds},
    aggregate: :avg
  )

Info and discovery:

TimelessMetrics.info(:metrics)
TimelessMetrics.list_metrics(:metrics)
TimelessMetrics.list_series(:metrics, "cpu_usage")
TimelessMetrics.label_values(:metrics, "cpu_usage", "host")

Use the HTTP API

Prometheus text ingest:

curl -X POST http://localhost:8428/api/v1/import/prometheus \
  -H "Content-Type: text/plain" \
  --data-binary '
cpu_usage{host="web-1"} 73.2
cpu_usage{host="web-2"} 61.8
'

VictoriaMetrics JSON-line ingest:

curl -X POST http://localhost:8428/api/v1/import \
  -H "Content-Type: application/json" \
  --data-binary '
{"metric":{"__name__":"cpu_usage","host":"web-1"},"values":[73.2],"timestamps":[1700000000]}
'

Native range query:

curl 'http://localhost:8428/api/v1/query_range?metric=cpu_usage&host=web-1&from=1700000000&to=1700003600&step=60'

Prometheus-compatible range query:

curl 'http://localhost:8428/prometheus/api/v1/query_range?query=cpu_usage{host="web-1"}&start=1700000000&end=1700003600&step=60'

Health and Operations

Lightweight health:

curl http://localhost:8428/health

More detailed diagnostics:

curl http://localhost:8428/health/detailed

Elixir operations:

TimelessMetrics.flush(:metrics)
TimelessMetrics.backup(:metrics, "/tmp/metrics-backup")

Product Features

TimelessMetrics also includes:

• annotations
• alerts
• metric metadata
• forecasting
• anomaly detection
• SVG charts
• dashboard
• scrape target management

Those remain Elixir-side application features layered on top of the rust-default storage engine.

Benchmarks

The maintained benchmark set is:

• bench/write_bench.exs
• bench/http_concurrency.exs
• bench/realistic_workload.exs
• bench/tsbs_bench.exs
• bench/vs_victoriametrics.exs

See ../bench/README.md for when to use each one.