.TH BIRD-EXPORTER 1 "December 2024" "bird-exporter 0.1.0" "User Commands"
.SH NAME
bird-exporter \- Prometheus exporter for BIRD routing daemon
.SH SYNOPSIS
.B bird-exporter
[\fIOPTIONS\fR]
.SH DESCRIPTION
.B bird-exporter
is a Prometheus metrics exporter for the BIRD routing daemon. It connects to
BIRD's control socket and exports metrics about protocols, routes, and BGP
sessions in a format that can be scraped by Prometheus.
.PP
The exporter periodically queries BIRD for protocol information and caches the
results to minimize load on the BIRD daemon. The cache is updated at a
configurable interval (default: 60 seconds) and served to Prometheus on each
scrape request.
.SH OPTIONS
.TP
.B \-web.listen\-address \fIstring\fR
Address to listen on for web interface and telemetry (default: ":9324")
.TP
.B \-bird.socket \fIstring\fR
Path to BIRD control socket (default: "/var/run/bird/bird.ctl")
.TP
.B \-period \fIduration\fR
Period between scrapes of BIRD data (default: 60s)
.TP
.B \-debug
Enable debug logging (default: false)
.SH METRICS
The exporter provides the following metrics:
.TP
.B bird_protocol_up
Protocol status (1 = up, 0 = down). Labels: name, proto, table, info
.TP
.B bird_bgp_state
BGP session state (1 = Established, 0 = other). Labels: name, neighbor_address, neighbor_as, local_as, neighbor_id
.TP
.B bird_route_imported
Number of imported routes. Labels: name, proto, channel, table
.TP
.B bird_route_filtered
Number of filtered routes. Labels: name, proto, channel, table
.TP
.B bird_route_exported
Number of exported routes. Labels: name, proto, channel, table
.TP
.B bird_route_preferred
Number of preferred routes. Labels: name, proto, channel, table
.TP
.B bird_route_import_updates_total
Total number of import updates. Labels: name, proto, channel, table
.TP
.B bird_route_import_withdraws_total
Total number of import withdraws. Labels: name, proto, channel, table
.TP
.B bird_route_import_rejected_total
Total number of rejected imports. Labels: name, proto, channel, table
.TP
.B bird_route_import_filtered_total
Total number of filtered imports. Labels: name, proto, channel, table
.TP
.B bird_route_import_ignored_total
Total number of ignored imports. Labels: name, proto, channel, table
.TP
.B bird_route_import_accepted_total
Total number of accepted imports. Labels: name, proto, channel, table
.TP
.B bird_route_export_updates_total
Total number of export updates. Labels: name, proto, channel, table
.TP
.B bird_route_export_withdraws_total
Total number of export withdraws. Labels: name, proto, channel, table
.TP
.B bird_route_export_rejected_total
Total number of rejected exports. Labels: name, proto, channel, table
.TP
.B bird_route_export_filtered_total
Total number of filtered exports. Labels: name, proto, channel, table
.TP
.B bird_route_export_accepted_total
Total number of accepted exports. Labels: name, proto, channel, table
.TP
.B bird_bgp_hold_timer_seconds
BGP hold timer in seconds. Labels: name, neighbor_address
.TP
.B bird_bgp_keepalive_timer_seconds
BGP keepalive timer in seconds. Labels: name, neighbor_address
.TP
.B bird_bgp_send_hold_timer_seconds
BGP send hold timer in seconds. Labels: name, neighbor_address
.SH CONFIGURATION
Default configuration can be set in \fB/etc/default/bird-exporter\fR. The file
should contain a BIRD_EXPORTER_ARGS variable with command line arguments.
.PP
Example:
.PP
.nf
.RS
BIRD_EXPORTER_ARGS="-period=60s -bird.socket=/var/run/bird/bird.ctl"
.RE
.fi
.SH EXAMPLES
Start the exporter with default settings:
.PP
.nf
.RS
bird-exporter
.RE
.fi
.PP
Start with custom BIRD socket path:
.PP
.nf
.RS
bird-exporter -bird.socket=/run/bird.ctl
.RE
.fi
.PP
Start with custom scrape interval and listen address:
.PP
.nf
.RS
bird-exporter -period=30s -web.listen-address=:9999
.RE
.fi
.PP
Start with debug logging enabled:
.PP
.nf
.RS
bird-exporter -debug
.RE
.fi
.PP
Query metrics using curl:
.PP
.nf
.RS
curl http://localhost:9324/metrics
.RE
.fi
.SH FILES
.TP
.B /etc/default/bird-exporter
Default configuration file
.TP
.B /var/run/bird/bird.ctl
Default BIRD control socket path
.TP
.B /lib/systemd/system/bird-exporter.service
Systemd service unit file
.SH PERMISSIONS
The exporter needs read/write access to the BIRD control socket. When running
as a systemd service, it runs as the \fBbird\fR user which should have
appropriate permissions.
.SH SEE ALSO
.BR bird (1),
.BR birdc (1),
.BR prometheus (1)
.PP
Project homepage: https://git.ipng.ch/ipng/bird-exporter
.SH AUTHOR
BIRD Exporter Authors