Prometheus Metrics

This page catalogs the OxiDNS Prometheus endpoint and metrics. Scrape only enabled subsystems; an absent optional metric does not necessarily indicate a failure.

Prometheus Metrics

GET /api/metrics

This endpoint is registered when the API is enabled. It is the single Prometheus text endpoint; plugins do not expose separate stats/metrics HTTP endpoints.

Current exported metrics include:

• query_total
• query_error_total
• query_inflight
• query_latency_count
• query_latency_sum_ms
• cache_lookup_total
• cache_hit_total
• cache_miss_total
• cache_expired_total
• cache_insert_total
• cache_skip_total
• cache_lazy_refresh_total
• cache_entry_count
• forward_query_total
• forward_success_total
• forward_error_total
• forward_timeout_total
• forward_latency_count
• forward_latency_sum_ms
• forward_incomplete_alias_selected_total
• forward_upstream_query_total
• forward_upstream_success_total
• forward_upstream_error_total
• forward_upstream_timeout_total
• forward_upstream_latency_count
• forward_upstream_latency_sum_ms
• fallback_primary_total
• fallback_primary_error_total
• fallback_secondary_total
• blackhole_block_total
• hosts_hit_total
• hosts_miss_total
• ratelimit_allowed_total
• ratelimit_rejected_total
• ip_selector_probe_total
• ip_selector_probe_latency_count
• ip_selector_probe_latency_sum_ms
• ip_selector_selected_total
• ip_selector_dropped_probe_total
• ip_selector_cache_entries
• network_resolver_cache_hit_total
• network_resolver_cache_miss_total
• network_resolver_error_total
• network_resolver_refresh_total
• network_resolver_refresh_latency_ms_total
• network_upstream_pool_refresh_total
• network_upstream_pool_refresh_latency_ms_total
• server_request_total
• server_completed_total
• server_controlled_total
• server_failed_total
• server_inflight
• server_latency_count
• server_latency_sum_ms
• ipset_entries_total
• ipset_dropped_total
• ipset_write_total
• ipset_write_error_total
• nftset_entries_total
• nftset_dropped_total
• nftset_write_total
• nftset_write_error_total
• ros_address_list_observe_total
• ros_address_list_dropped_total
• ros_address_list_sync_error_total
• ros_address_list_sync_timeout_total
• ros_address_list_pending_observations / ros_address_list_managed_entries
• ros_address_list_write_success_total / ros_address_list_write_error_total
• ros_address_list_last_write_success_timestamp_seconds
• ros_address_list_coalesced_total
• ros_address_list_reconnect_total / ros_address_list_connect_attempt_total / ros_address_list_backoff_total
• ros_address_list_reconcile_error_total / ros_address_list_last_reconcile_success_timestamp_seconds
• ros_address_list_degraded / ros_address_list_cleanup_error_total
• ros_route_observe_total / ros_route_dropped_total
• ros_route_sync_error_total / ros_route_sync_timeout_total
• ros_route_write_success_total / ros_route_write_error_total
• ros_route_pending_observations / ros_route_managed_entries
• ros_route_coalesced_total / ros_route_delete_deferred_total
• ros_route_reconnect_total / ros_route_connect_attempt_total / ros_route_backoff_total
• ros_route_connection_check_error_total / ros_route_reconcile_error_total
• ros_route_last_write_success_timestamp_seconds / ros_route_last_reconcile_success_timestamp_seconds
• ros_route_degraded / ros_route_cleanup_error_total
• reverse_lookup_ptr_hit_total
• reverse_lookup_ptr_miss_total
• reverse_lookup_cache_insert_total
• reverse_lookup_cache_entries
• download_success_total
• download_failure_total
• download_timeout_total
• http_request_dispatch_total
• http_request_error_total
• http_request_dropped_total
• script_run_total
• script_success_total
• script_error_total
• script_timeout_total
• reload_trigger_total
• reload_error_total
• reload_provider_reload_total
• reload_provider_reload_error_total
• cron_job_run_total
• cron_job_skipped_total
• cron_executor_error_total

These metrics use low-cardinality plugin-level labels such as plugin_tag, name, kind, reason, result, and protocol. server_* additionally carries a protocol label (udp/tcp/dot/quic/doh). forward_upstream_* carries an upstream label whose value is the upstream tag (or its resolved address when no tag is configured); since the upstream set is fixed at startup and bounded, this stays a low-cardinality dimension. High-cardinality values such as qname or client IP are intentionally excluded from the generic metrics layer; use query_recorder when per-query detail is needed.