374 lines
8.4 KiB
Markdown
374 lines
8.4 KiB
Markdown
# 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:
|
|
```sh
|
|
./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:
|
|
```sh
|
|
./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:
|
|
```sh
|
|
./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:
|
|
```sh
|
|
./bird-exporter -debug
|
|
```
|
|
|
|
## Building
|
|
|
|
### Prerequisites
|
|
|
|
- Go 1.21 or later
|
|
- Make (optional)
|
|
|
|
### Build Commands
|
|
|
|
Using Make:
|
|
```sh
|
|
make build
|
|
```
|
|
|
|
Using Go directly:
|
|
```sh
|
|
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:
|
|
```sh
|
|
make test
|
|
```
|
|
|
|
Using Go directly:
|
|
```sh
|
|
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:
|
|
```sh
|
|
./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`:
|
|
```ini
|
|
[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:
|
|
```sh
|
|
systemctl enable bird-exporter
|
|
systemctl start bird-exporter
|
|
```
|
|
|
|
### Prometheus Configuration
|
|
|
|
Add to prometheus.yml:
|
|
```yaml
|
|
scrape_configs:
|
|
- job_name: 'bird'
|
|
static_configs:
|
|
- targets: ['localhost:9324']
|
|
```
|
|
|
|
## Prometheus Queries
|
|
|
|
### Example Queries
|
|
|
|
Count protocols by state:
|
|
```promql
|
|
count by (state) (bird_protocol_up)
|
|
```
|
|
|
|
Count established BGP sessions:
|
|
```promql
|
|
sum(bird_bgp_state)
|
|
```
|
|
|
|
Total imported routes by protocol type:
|
|
```promql
|
|
sum by (proto) (bird_route_imported)
|
|
```
|
|
|
|
BGP sessions with low hold timer (potential flapping):
|
|
```promql
|
|
bird_bgp_hold_timer_seconds < 30
|
|
```
|
|
|
|
Import reject rate:
|
|
```promql
|
|
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:
|
|
```sh
|
|
./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:
|
|
```sh
|
|
ls -la /var/run/bird/bird.ctl
|
|
```
|
|
|
|
Verify BIRD is running:
|
|
```sh
|
|
birdc show status
|
|
```
|
|
|
|
Check exporter logs for connection errors:
|
|
```sh
|
|
journalctl -u bird-exporter -f
|
|
```
|
|
|
|
### Incorrect Metric Values
|
|
|
|
Check exporter logs for parse errors:
|
|
```sh
|
|
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
|