Collectors

A collector produces metrics on a timer. Every [[collectors]] entry becomes one engine task polling at its interval and shipping values out to rules and adapters.

Anatomy

[[collectors]]
name     = "cpu"        # required, your handle
kind     = "cpu"        # defaults to `name` when omitted
interval = "5s"         # how often to poll, default 5s
labels   = {}           # reserved, see Labels below
filter   = ""           # reserved, see Filtering below
plugin   = ""           # explicit plugin crate (rare)
[collectors.opts]
# kind-specific options

Same kind, different name lets you run several instances:

[[collectors]]
name = "api"
kind = "http"
[collectors.opts]
url = "https://api.example.com/healthz"

[[collectors]]
name = "homepage"
kind = "http"
[collectors.opts]
url = "https://example.com"

Reference each via api::http.status and homepage::http.latency in rules.

Built-in kinds

The default build ships these. Plugins extend the list.

Slim builds

Each built-in is gated behind a Cargo feature on nanook-cli. The default build enables every collector; drop the ones you do not need to shave the binary, the dependency tree, and startup time. To opt in to a custom subset:

cargo build -p nanook-cli \
  --no-default-features \
  --features "collector-cpu collector-mem collector-disk adapter-stdout action-log"

The same pattern applies to adapters (adapter-*) and channel actions: action-log, action-exec, action-webhook, action-discord, action-slack. To recover the full out-of-the-box set without re-listing every flag, opt in to one of the umbrella features instead: collectors-default, adapters-default, actions-default.

If you want the full set plus an extra cdylib loaded at runtime, keep the defaults on and add the plugin separately. See Plugins.

Filtering

Set filter on a collector to drop samples before they reach the engine bus. The expression uses the filter sub-language of nanook-expr and can match on name, src, and any label key (including the per-collector labels merged in by the same block).

[[collectors]]
name = "net"
filter = 'iface like "eth*" || iface like "wg*"'

A sample whose filter raises a resolver error (for example an iface reference on a metric that has no iface label) is dropped, matching the "filter didn't match" intuition. Bad filter syntax surfaces at nanook check and at startup as nanook::expr::*.

Labels

Per-collector labels = { ... } are merged onto every emitted sample before the global [labels] block. A label already on the metric wins, then the per-collector entry, then the global default.

[[collectors]]
name = "net"
labels = { tier = "edge" }

[labels]
host = "node-1"
env  = "prod"

Probing once

See what a collector returns without booting the whole agent:

nanook probe cpu
nanook probe api --warmup 1000   # discard first read after 1s, then measure

Pausing / resuming live

While the agent runs:

nanook ctl pause cpu
nanook ctl resume cpu
nanook ctl trigger cpu     # fire one read manually

See ctl.

Writing your own

A collector is a Rust crate that implements the Collector trait and ships as a cdylib. See Plugins for the build layout and ABI version pinning.