owl reads configuration from three layers, in order of increasing precedence:

  1. config.yml — the structured fields below. Mounted into the container at /etc/owl/config.yml by default.
  2. Environment variables — convenient for operational values and secrets. OWL_LISTEN_ADDR, OWL_LOG_LEVEL, OWL_DB_PATH, OWL_ALERT_WEBHOOK_URL shadow their YAML equivalents.
  3. CLI flags — --config <path>, --check-config, --version.

Validate any file without starting the server:

owl --config /etc/owl/config.yml --check-config

Most fields take effect on live reload (SIGHUP or POST /-/reload); the Reload section of the readme lists the two that still need a restart (listen, and storage.path / storage.retention).

Schema

Config

Field Type Default Description
listen string "127.0.0.1:9090" HTTP listen address, e.g. "0.0.0.0:9090".
log_level string "info" slog level: debug, info, warn, or error.
storage StorageConfig — SQLite storage settings.
scrape ScrapeConfig — Defaults applied to every scrape target.
targets []TargetConfig — Explicit /metrics endpoints to scrape.
docker DockerConfig — Docker integration (per-container metrics plus label-based target discovery).
host HostConfig — Linux host collector reading /proc and /sys.
dashboards DashboardsConfig — Where dashboard JSON files live, plus optional mtime watcher.
alerts AlertsConfig — Threshold alert rules and the webhook delivery target.
events EventsConfig — Events ingestion stack (file_tail and docker_logs sources).

AlertsConfig

Field Type Default Description
webhook_url string — Outbound webhook URL the alerter POSTs to when a rule fires or resolves.
rules []AlertRule — Inline list of threshold alert rules evaluated on every tick.

[]AlertRule

Field Type Default Description
name string — Human-readable rule name included in the webhook payload.
expr string — PromQL expression evaluated on every alerter tick.
op string — Comparison operator: ">", ">=", "<", or "<=".
threshold float64 0 Numeric threshold the expression is compared against.
for int64 0 How long the condition must hold continuously before the rule fires.

DashboardsConfig

Field Type Default Description
dir string "/etc/owl/dashboards" Directory containing dashboard JSON files; loaded recursively on startup and reload.
watch bool false Enable the mtime-based watcher that hot-reloads dashboards when their files change.
watch_interval int64 5000000000 How often the watcher polls file mtimes; ignored when watch is false.

DockerConfig

Field Type Default Description
enabled bool false Master switch for the Docker integration; off disables both metrics and discovery.
socket_path string "/var/run/docker.sock" Path to the Docker daemon socket inside the owl container.
metrics DockerMetricsConfig — Per-container metrics collector (CPU, memory, network, block I/O).
discovery DockerDiscoveryConfig — Auto-discovery of scrape targets from container labels.

DockerDiscoveryConfig

Field Type Default Description
enabled bool false Enable container-label scrape-target discovery.
label_prefix string "owl.scrape" Label prefix used to opt containers into discovery (e.g. "owl.scrape").
interval int64 30000000000 How often the discovery loop re-reads the container list.

DockerMetricsConfig

Field Type Default Description
enabled bool false Enable the per-container metrics collector.
interval int64 30000000000 How often the collector samples each container's stats.

EventsConfig

Field Type Default Description
enabled bool false Master switch for the events ingestion stack; off disables all source drivers.
sources []EventSourceConfig — Ordered list of event sources to ingest from.

[]EventSourceConfig

Field Type Default Description
name string — Logical source name; must be unique across all sources.
driver string — Ingestion driver: file_tail or docker_logs.
interval int64 0 How often to poll for new records; 0 uses the driver default.
from string — Where to start reading: "beginning" or "end" (default end).
path string — Filesystem path of the log file; required for file_tail driver.
container string — Docker container name or ID to tail; required for docker_logs driver.
format string — Record parser: json, regex, or plain.
pattern string — RE2 regular expression with named groups; required when format=regex.
match []MatchRule — Optional filter rules; all must match for the record to be ingested.
mapping MappingConfig — Field extractors that map parsed record fields to an Event.
render string — Go text/template string rendered into Event.Summary; receives the parsed record as data.

MappingConfig

Field Type Default Description
ts string — JSONPath or field name of the timestamp field; omit to use ingest time.
kind string — Literal event kind or JSONPath expression; required.
payload map[string]string — Key→JSONPath/literal map of extra fields stored in the event payload.

[]MatchRule

Field Type Default Description
field string — Name of the parsed record field to test.
equals string — Record field must equal this value exactly.
contains string — Record field must contain this substring.

HostConfig

Field Type Default Description
enabled bool false Enable the Linux host collector; requires /proc and /sys to be readable.
proc_path string "/proc" Path to the procfs root, typically /proc or /host/proc inside a container.
sys_path string "/sys" Path to the sysfs root, typically /sys or /host/sys inside a container.
interval int64 30000000000 How often the host collector samples; 0 uses the built-in default.

ScrapeConfig

Field Type Default Description
default_interval int64 30000000000 Default scrape interval applied to targets that do not override it.
default_timeout int64 10000000000 Default HTTP timeout applied to targets that do not override it.

StorageConfig

Field Type Default Description
path string "/var/lib/owl/owl.db" Filesystem path to the SQLite database file.
retention RetentionPolicy — Time- and size-based retention policy.
head_window int64 7200000000000 How long recent samples stay uncompressed before the chunk flusher encodes them.
flush_interval int64 600000000000 How often the chunk flusher runs; 0 falls back to the default.

RetentionPolicy

Field Type Default Description
time int64 2592000000000000 Maximum sample age; older samples are deleted on each retention tick.
size int64 0 Maximum on-disk size in bytes; 0 disables the size cap.
interval int64 1800000000000 How often the retention worker runs; 0 falls back to the default.

[]TargetConfig

Field Type Default Description
name string — Logical target name shown in the UI and attached as the "job" label.
url string — HTTP URL of the Prometheus-format /metrics endpoint to scrape.
interval int64 0 Per-target scrape interval; overrides scrape.default_interval.
timeout int64 0 Per-target HTTP timeout; overrides scrape.default_timeout.
labels map[string]string — Static labels attached to every sample scraped from this target.
keep []string — Regex allow-list of metric names; empty stores everything.
drop []string — Regex deny-list of metric names applied after keep.
auth ptr — Optional HTTP authentication for this target (bearer, basic, headers).
tls ptr — Optional TLS settings for https:// targets (skip-verify, custom CA).

Common scenarios

  • Pointing an external Prometheus at owl — drop or rename the owl-self target. owl will still expose /metrics; whatever scrapes it stores the samples.
  • Keeping the SQLite footprint down — add per-target keep / drop regex filters under targets[]. The bundled examples filter Traefik's bucket series, which are responsible for the bulk of its cardinality.
  • Hot-swapping the webhook — change alerts.webhook_url and reload. In-flight POSTs finish against the old URL; the next state transition uses the new one.
  • Auto-reloading dashboard edits — set dashboards.watch: true and an dashboards.watch_interval. Off by default because owl prefers not to poll your filesystem unless asked.