# 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