axiom-hostmetrics

A terminal UI that scrapes host metrics with the upstream OpenTelemetry hostmetricsreceiver and ships them to Axiom via OTLP/HTTP.

Warning

This is meant to provide an easy way to send Metrics to Axiom quickly—in production systems please use the OTel collector with host_metrics.

Install

With Homebrew:

brew install axiomhq/tap/axiom-hostmetrics

Build from source (Go 1.22+):

go install github.com/axiomhq/axiom-hostmetrics/cmd/axiom-hostmetrics@latest

Or build a stripped release binary:

go build -trimpath -ldflags='-s -w' ./cmd/axiom-hostmetrics

First run

Running with no config launches a wizard that asks for:

• Dataset — the destination Axiom dataset (must match [a-zA-Z0-9_-]+)
• Token — an Axiom Advanced API Token, xaat-…
• Endpoint — pick US East, EU Central, or supply a custom URL

The wizard saves to $XDG_CONFIG_HOME/axiom-hostmetrics/config.toml (~/.config/axiom-hostmetrics/config.toml on most systems) with mode 0600.

To force the wizard on a subsequent run, pass --reconfigure.

Config

version  = 1
dataset  = "my-dataset"
endpoint = "https://us-east-1.aws.edge.axiom.co"
token    = "xaat-..."
# interval omitted when it matches the default (10s)

Interval must be between 1s and 60s. The interval line is omitted when it equals the default so the file stays minimal.

Environment overrides

Variable	Overrides
AXIOM_TOKEN	token
AXIOM_DATASET	dataset
AXIOM_ENDPOINT	endpoint

Env vars are applied after the file loads. An empty env var does not override.

What it sends

All ten default hostmetricsreceiver scrapers are enabled: cpu, load, memory, disk, filesystem, network, paging, processes, process, system.

Every batch carries a host.name resource attribute, resolved once at startup via os.Hostname(). If the call fails the attribute is omitted and a warning is written to the log.

Wire format:

• POST <endpoint>/v1/metrics
• Authorization: Bearer <token>
• X-Axiom-Dataset: <dataset>
• OTLP protobuf body, compressed with zstd

Persistent log

In addition to the in-memory log buffer rendered in the TUI, axiom-hostmetrics appends to $XDG_STATE_HOME/axiom-hostmetrics/log, rotating at 5 MB and keeping three prior generations (log.1, log.2, log.3). Lines containing the token-prefix xaat- are dropped on write as a defensive guard — the file never receives a raw or masked token.

If the log file cannot be opened, the warning is printed to stderr at startup and the TUI continues without persistent logging.

Known limitations

• Interval change causes a brief gap. SetInterval shuts the scraper, rebuilds it with the new interval, and restarts it. The gap is typically a few milliseconds; the exporter is not interrupted.
• Empty validation ping. Startup validation sends an empty OTLP payload to confirm endpoint / token / dataset are accepted before the dashboard starts. This works against Axiom today; if a future server-side change begins rejecting empty payloads, the failure is surfaced verbatim with r/q offered — there is no silent downgrade to a synthetic point.