Metrics¶

Gitfeed exposes Prometheus metrics on /metrics at http.address. Three metric families cooperate to produce the operator-visible surface:

oxfeed_gitfeed_* — converter state and history events: how many feed versions exist, when HEAD changed, when history was rewritten.
oxfeed_source_command_* — only registered when git.command_source is configured. Same metric set as the standalone OX Feed Command Source service.
pdns_platform_version_info — single info gauge with the build version as a label.

The default Go runtime and process collectors from the standard Prometheus client are also exposed (go_*, process_*). They are not listed here.

Label cardinality watch-outs¶

Most metrics are unlabelled. Three carry labels:

oxfeed_gitfeed_info — labelled by git_path, git_repo, feed_path, feed_uuid. Each instance produces exactly one series for its lifetime, so cardinality is bounded by the number of instances. Restart resets feed_uuid only when feed.namespace_per_code changes; otherwise it is stable.
oxfeed_gitfeed_fetch_error_message_total — labelled by the raw go-git error string. This is the one to watch. Transient network errors with embedded addresses, hostnames, or process IDs can push the label set unbounded over time. If you ingest these metrics long-term, drop the error label at scrape time or alert on its cardinality.
oxfeed_source_command_exec_exitcode_total and oxfeed_source_command_exec_error_message_total (command-source overlay only) — same caveats as for the standalone command source.

Is the converter healthy?¶

Metric	Type	Meaning
`oxfeed_gitfeed_info`	Gauge	Set to `1` per instance, labelled by `git_path`, `git_repo`, `feed_path`, `feed_uuid`. Useful as a join target.
`oxfeed_gitfeed_head_change_total`	Counter	Number of times the git HEAD changed and produced a wake-up.
`pdns_platform_version_info`	Gauge	Build version exposed as a label.

For a feed that should see updates daily, alert when no HEAD change has been seen recently:

# No HEAD change in the last 24h on this instance.
increase(oxfeed_gitfeed_head_change_total[24h]) == 0

For a feed that is naturally quiet, treat head_change_total as informational and rely on the absence of errors instead.

Are commits being written?¶

Metric	Type	Meaning
`oxfeed_gitfeed_versions`	Gauge	Sequential number of the highest feed version written. Monotonic per history; resets on rewrite.
`oxfeed_gitfeed_current_version`	Gauge	The `version` field of the latest snapshot — encodes both the sequential number and the leading commit hash bytes.
`oxfeed_gitfeed_current_version_entries`	Gauge	Number of domain entries in the latest snapshot written. `NaN` before the first snapshot.
`oxfeed_gitfeed_feed_size_bytes`	Gauge	Total bytes occupied by snapshots, deltas, and `feed-codes.json` under `feed.root`.

feed_size_bytes is the easiest signal for a runaway feed. If it grows monotonically over weeks, downstream consumers may not be cleaning up stale files, or the feed itself is growing through content additions.

current_version_entries falling to a much lower value than usual between releases is a useful signal for accidentally truncated CSVs.

Is fetching working?¶

These metrics are only meaningful for remote roots (git.root containing :).

Metric	Type	Meaning
`oxfeed_gitfeed_fetch_error_total`	Counter	Total git fetch errors. Increments on transient network issues, auth refresh failures, etc.
`oxfeed_gitfeed_fetch_error_message_total`	Counter (per error)	Per-message counter. High cardinality — see the watch-out above.

There is no companion success-timestamp gauge for fetches; pair the error counter with oxfeed_gitfeed_head_change_total to infer pipeline health. A flat HEAD-change rate plus a rising fetch error rate means the service is online but cannot reach the remote.

# Fetch errors over the last 10 minutes.
rate(oxfeed_gitfeed_fetch_error_total[10m]) > 0

Is history stable?¶

Metric	Type	Meaning
`oxfeed_gitfeed_reset_total`	Counter	Number of times the feed was reset due to a rewritten git history.
`oxfeed_gitfeed_version_remove_total`	Counter	Number of snapshot or delta versions removed because the corresponding commit disappeared from the linear log.

Both counters move only when history is rewritten — force-push, rebase, or a master branch reset on the upstream repository. A single rewrite typically increments reset_total by one and version_remove_total by the number of versions that fell off the end of the history.

# Alert on any history rewrite in the last hour.
increase(oxfeed_gitfeed_reset_total[1h]) > 0

Resets force every downstream client to re-snap from the new history. Alert on this even when it is intentional, so the team knows when re-snap load is expected.

Command-source-only metrics¶

These metrics are registered the first time the command-source overlay is initialised; they stay at zero on instances that do not use it. They share the same definitions as the standalone OX Feed Command Source service.

Metric	Type	Meaning
`oxfeed_source_command_exec_total`	Counter	Total invocations of the source command since startup.
`oxfeed_source_command_exec_success_last_time_seconds`	Gauge	Unix timestamp of the last successful run (including exit `11`).
`oxfeed_source_command_exec_error_total`	Counter	Runs that failed: any exit code other than `0` or `11`, plus output-parsing failures and timeouts.
`oxfeed_source_command_exec_exitcode_total`	Counter (per exit code)	Per-exit-code counter. Cardinality bounded by codes the command actually returns.
`oxfeed_source_command_exec_error_message_total`	Counter (per error)	Per-error-message counter. High cardinality — drop the label at scrape time if you ingest long-term.
`oxfeed_source_command_exec_duration_seconds`	Histogram	Wall-clock duration of each command run. Includes time spent waiting if the command supports `--wait`.
`oxfeed_source_command_update_channel_blocked_seconds`	Histogram	Time the source spent blocked publishing an update to gitfeed.
`oxfeed_source_command_feed_change_total`	Counter	Feed CSV content actually changed (hash differs from the previous accepted run).
`oxfeed_source_command_feed_change_last_time_seconds`	Gauge	Unix timestamp of the last feed content change.
`oxfeed_source_command_codes_change_total`	Counter	`feed-codes.json` content actually changed.
`oxfeed_source_command_codes_change_last_time_seconds`	Gauge	Unix timestamp of the last codes change.

The *_change_total counters track content changes, not command invocations. A command that runs every five seconds against unchanged data leaves the change counters flat while oxfeed_source_command_exec_success_last_time_seconds updates on every run. That is the expected steady state for quiet feeds — alert on the absence of successful execs, not on the absence of changes.

# No successful command run in the last 30 minutes.
time() - oxfeed_source_command_exec_success_last_time_seconds > 1800

PromQL: histogram quantile¶

For command-source exec duration p95:

histogram_quantile(0.95,
  rate(oxfeed_source_command_exec_duration_seconds_bucket[5m]))

Long tails on exec_duration_seconds are usually the command waiting for source data to change (with --wait), not a slow source. To distinguish, also look at feed_change_total: high duration + low change rate is normal idle behaviour; high duration + high change rate means the command itself is slow.