bird-exporter/doc/DETAILS.md

BIRD Exporter - Detailed Documentation

Overview

bird-exporter is a Prometheus exporter for the BIRD routing daemon. It parses the output of birdc show proto all and exposes metrics in Prometheus format.

Architecture

The exporter consists of three main components:

1. Parser - Parses BIRD protocol output into structured data
2. Collector - Implements Prometheus collector interface
3. HTTP Server - Serves metrics on /metrics endpoint

Input Format

The exporter reads output from birdc show proto all, which provides detailed information about all configured protocols. Each protocol block contains:

• Protocol name, type, table, state, and timestamp
• Protocol-specific information (BGP state, OSPF status, etc.)
• One or more channels (typically ipv4 and/or ipv6)
• Route statistics per channel
• Import/export statistics per channel

Supported Protocol Types

• Device - Interface tracking
• Direct - Directly connected routes
• Kernel - Kernel routing table synchronization
• Static - Static routes
• OSPF - OSPF routing protocol
• BGP - Border Gateway Protocol

Exported Metrics

Protocol Status Metrics

bird_protocol_up

• Type: Gauge
• Description: Protocol operational status (1=up, 0=down)
• Labels: name, proto, table, info

BGP-Specific Metrics

bird_bgp_state

• Type: Gauge
• Description: BGP session state (1=Established, 0=other)
• Labels: name, neighbor_address, neighbor_as, local_as, neighbor_id

bird_bgp_hold_timer_seconds

• Type: Gauge
• Description: Current BGP hold timer value in seconds
• Labels: name, neighbor_address

bird_bgp_keepalive_timer_seconds

• Type: Gauge
• Description: Current BGP keepalive timer value in seconds
• Labels: name, neighbor_address

bird_bgp_send_hold_timer_seconds

• Type: Gauge
• Description: Current BGP send hold timer value in seconds
• Labels: name, neighbor_address

Route Metrics

All route metrics include labels: name, proto, channel, table

bird_route_imported

• Type: Gauge
• Description: Number of routes currently imported

bird_route_exported

• Type: Gauge
• Description: Number of routes currently exported

bird_route_preferred

• Type: Gauge
• Description: Number of preferred routes

Route Change Statistics

All statistics are counters with labels: name, proto, channel, table

Import Statistics:

• bird_route_import_updates_total
• bird_route_import_withdraws_total
• bird_route_import_rejected_total
• bird_route_import_filtered_total
• bird_route_import_ignored_total
• bird_route_import_accepted_total

Export Statistics:

• bird_route_export_updates_total
• bird_route_export_withdraws_total
• bird_route_export_rejected_total
• bird_route_export_filtered_total
• bird_route_export_accepted_total

Configuration

Command-Line Flags

-web.listen-address (default: :9324) The address and port to listen on for HTTP requests.

Example:

./bird-exporter -web.listen-address=:9100

-bird.socket (default: /var/run/bird/bird.ctl) Path to the BIRD control socket for communication with the BIRD daemon.

Example:

./bird-exporter -bird.socket=/run/bird.ctl

-period (default: 60s) Time interval between BIRD data scrapes. The exporter caches BIRD data and updates it periodically at this interval.

Example:

./bird-exporter -period=30s

-debug (default: false) Enable debug logging. When enabled, additional log messages are printed including:

• "Performing initial scrape..."
• "BIRD: show protocols all"
• "Successfully scraped N protocols"

Without debug mode, only essential startup and operational messages are logged.

Example:

./bird-exporter -debug

Building

Prerequisites

• Go 1.21 or later
• Make (optional)

Build Commands

Using Make:

make build

Using Go directly:

go build -o bird-exporter ./cmd/bird-exporter/

Build Output

The binary will be created in the project root directory:

• Binary name: bird-exporter
• Size: ~12MB (uncompressed)

Testing

Running Tests

Using Make:

make test

Using Go directly:

go test -v ./cmd/bird-exporter/

Test Coverage

The test suite includes:

• Protocol parsing tests (Device, Direct, Kernel, Static, OSPF, BGP)
• Channel parsing tests
• Route statistics parsing tests
• BGP-specific field parsing tests
• Error handling tests (missing files, empty files)
• Integration test with real birdc output

Test Fixtures

Test fixtures are located in cmd/bird-exporter/testdata/:

• sample_output.txt - Minimal test fixture with all protocol types

Deployment

Running Locally

For development or testing:

./bird-exporter
curl http://localhost:9324/metrics

Running in Production

The exporter communicates with BIRD via its control socket. Ensure the exporter has permission to access the BIRD socket (typically /var/run/bird/bird.ctl).

Systemd Service

Create /etc/systemd/system/bird-exporter.service:

[Unit]
Description=BIRD Exporter
After=network.target bird.service

[Service]
Type=simple
User=bird
ExecStart=/usr/local/bin/bird-exporter -period=60s
Restart=always

[Install]
WantedBy=multi-user.target

Enable and start the service:

systemctl enable bird-exporter
systemctl start bird-exporter

Prometheus Configuration

Add to prometheus.yml:

scrape_configs:
  - job_name: 'bird'
    static_configs:
      - targets: ['localhost:9324']

Prometheus Queries

Example Queries

Count protocols by state:

count by (state) (bird_protocol_up)

Count established BGP sessions:

sum(bird_bgp_state)

Total imported routes by protocol type:

sum by (proto) (bird_route_imported)

BGP sessions with low hold timer (potential flapping):

bird_bgp_hold_timer_seconds < 30

Import reject rate:

rate(bird_route_import_rejected_total[5m])

Limitations

1. BIRD v2 Only - The parser is designed for BIRD v2 output format. BIRD v1 compatibility is not guaranteed.

2. Periodic Updates - Metrics are updated at the configured scrape interval (default 60s). Changes in BIRD state may not be immediately reflected in metrics.

Troubleshooting

Debugging Connection Issues

Enable debug logging to see detailed information about BIRD communication:

./bird-exporter -debug

This will show:

• When the exporter queries BIRD
• What command is being sent
• How many protocols were successfully parsed

No Metrics Appearing

Check that the BIRD socket is accessible:

ls -la /var/run/bird/bird.ctl

Verify BIRD is running:

birdc show status

Check exporter logs for connection errors:

journalctl -u bird-exporter -f

Incorrect Metric Values

Check exporter logs for parse errors:

journalctl -u bird-exporter | grep -i error

High Memory Usage

The exporter loads the entire BIRD output into memory. For routers with many BGP sessions and large routing tables, this can consume significant memory. Monitor memory usage and consider resource limits.

Development

Project Structure

bird-exporter/
├── cmd/
│   └── bird-exporter/
│       ├── main.go           # Main program
│       ├── main_test.go      # Tests
│       └── testdata/         # Test fixtures
├── doc/
│   └── DETAILS.md           # This file
├── go.mod                   # Go module definition
├── Makefile                 # Build automation
└── README.md                # Quick start guide

Adding New Metrics

1. Define metric descriptor in NewBirdCollector()
2. Add metric to Describe() method
3. Extract data in parser if needed
4. Export metric in Collect() method
5. Add test coverage

Parser Architecture

The parser uses a state machine approach:

• Tracks current protocol being parsed
• Tracks current channel within protocol
• Uses regex patterns to match and extract fields
• Handles hierarchical structure through indentation

Future Enhancements

1. Additional Protocols - Support for RIP, Babel, BFD details, etc.
2. Neighbor Details - More detailed BGP neighbor information
3. Route Details - Export information about specific routes
4. Real-time Updates - Push updates instead of polling
5. Configuration Reload - Support SIGHUP for config reload
6. Multiple BIRD Instances - Support monitoring multiple BIRD instances

License

MIT License - See LICENSE file for details