Initial commit
This commit is contained in:
373
doc/DETAILS.md
Normal file
373
doc/DETAILS.md
Normal file
@@ -0,0 +1,373 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user