A Prometheus exporter for NetBird API that provides comprehensive metrics about your NetBird network peers, groups, users, networks, and DNS configuration. This exporter fetches data from the NetBird REST API, Groups API, Users API, Networks API, and DNS API and exposes it in Prometheus format.

The exporter provides the following metrics:

The exporter is configured via environment variables:

1. Log into your NetBird dashboard
2. Go to Settings → API Keys
3. Create a new API key with appropriate permissions
4. Copy the token and use it as NETBIRD_API_TOKEN

1. Clone this repository:

git clone https://github.com/matanbaruch/netbird-api-exporter
cd netbird-api-exporter

1. Create environment file:

cp env.example .env
# Edit .env with your NetBird API token

1. Start the exporter:

docker-compose up -d

Browse and install from Artifact Hub. See our Artifact Hub guide for more details:

# Install directly from OCI registry
helm upgrade --install netbird-api-exporter \
  oci://ghcr.io/matanbaruch/netbird-api-exporter/charts/netbird-api-exporter \
  --set netbird.apiToken=your_token_here

Install using Helm with the chart from GitHub packages:

# Add the chart repository
helm upgrade --install netbird-api-exporter \
  oci://ghcr.io/matanbaruch/netbird-api-exporter/charts/netbird-api-exporter \
  --set netbird.apiToken=your_token_here

Or with a values file:

# Create values.yaml
cat <<EOF > values.yaml
netbird:
  apiToken: "your_token_here"
  apiUrl: "https://api.netbird.io"

service:
  type: ClusterIP
  port: 8080

serviceMonitor:
  enabled: true  # if using Prometheus operator
EOF

# Install the chart
helm upgrade --install netbird-api-exporter \
  oci://ghcr.io/matanbaruch/netbird-api-exporter/charts/netbird-api-exporter \
  -f values.yaml

Use the pre-built image from GitHub packages:

docker run -d \
  -p 8080:8080 \
  -e NETBIRD_API_TOKEN=your_token_here \
  --name netbird-api-exporter \
  ghcr.io/matanbaruch/netbird-api-exporter:latest

Or build from source:

docker build -t netbird-api-exporter .
docker run -d \
  -p 8080:8080 \
  -e NETBIRD_API_TOKEN=your_token_here \
  --name netbird-api-exporter \
  netbird-api-exporter

1. Install dependencies:

go mod download

1. Build and run:

export NETBIRD_API_TOKEN=your_token_here
go build -o netbird-api-exporter
./netbird-api-exporter

• /metrics - Prometheus metrics endpoint
• /health - Health check endpoint (returns JSON)
• / - Information page with links

Add the following to your prometheus.yml:

scrape_configs:
  - job_name: "netbird-api-exporter"
    static_configs:
      - targets: ["localhost:8080"]
    scrape_interval: 30s
    metrics_path: /metrics

Here are some useful Prometheus queries:

# Total number of peers
netbird_peers

# Percentage of connected peers
(netbird_peers_connected{connected="true"} / netbird_peers) * 100

# Peers by operating system
sum by (os) (netbird_peers_by_os)

# Peers that haven't been seen in over 1 hour
(time() - netbird_peer_last_seen_timestamp) > 3600

# Number of peers requiring approval
netbird_peers_approval_required{approval_required="true"}

# Average accessible peers per peer
avg(netbird_peer_accessible_peers_count)

# Total number of groups
netbird_groups

# Groups with the most peers
topk(5, netbird_group_peers_count)

# Groups with the most resources
topk(5, netbird_group_resources_count)

# Average peers per group
avg(netbird_group_peers_count)

# Groups by issued method (API vs manual)
count by (issued) (netbird_group_info)

# Resource distribution by type across all groups
sum by (resource_type) (netbird_group_resources_by_type)

# Groups with no peers
netbird_group_peers_count == 0

# Groups with no resources
netbird_group_resources_count == 0

# Groups scrape error rate
rate(netbird_groups_scrape_errors_total[5m])

# Total number of users
netbird_users

# Users by role
sum by (role) (netbird_users_by_role)

# Users by status
sum by (status) (netbird_users_by_status)

# Service users vs regular users
netbird_users_service_users

# Blocked users
netbird_users_blocked

# Users by issuance type
sum by (issued) (netbird_users_by_issued)

# Users with restricted permissions
netbird_users_restricted

# Last login timestamp for each user
netbird_user_last_login_timestamp

# Auto groups assigned to each user
netbird_user_auto_groups_count

# User permissions by module and action
sum by (module, permission) (netbird_user_permissions)

# Total number of nameserver groups
netbird_dns_nameserver_groups

# Enabled vs disabled nameserver groups
netbird_dns_nameserver_groups_enabled

# Primary vs secondary nameserver groups
netbird_dns_nameserver_groups_primary

# Nameserver groups with the most domains
topk(5, netbird_dns_nameserver_group_domains_count)

# Nameserver groups with the most nameservers
topk(5, netbird_dns_nameservers)

# Nameserver distribution by type
sum by (ns_type) (netbird_dns_nameservers_by_type)

# Nameserver distribution by port
sum by (port) (netbird_dns_nameservers_by_port)

# Groups with DNS management disabled
netbird_dns_management_disabled_groups_count

# Average domains per nameserver group
avg(netbird_dns_nameserver_group_domains_count)

# Nameserver groups with no domains configured
netbird_dns_nameserver_group_domains_count == 0

# Total nameservers across all groups
sum(netbird_dns_nameservers)

# Total number of networks
netbird_networks

# Networks with the most routers
topk(5, netbird_network_routers_count)

# Networks with the most resources
topk(5, netbird_network_resources_count)

# Networks with the most policies
topk(5, netbird_network_policies_count)

# Networks with the most routing peers
topk(5, netbird_network_routing_peers_count)

# Average routers per network
avg(netbird_network_routers_count)

# Average resources per network
avg(netbird_network_resources_count)

# Networks with no routers
netbird_network_routers_count == 0

# Networks with no resources
netbird_network_resources_count == 0

# Networks with no policies
netbird_network_policies_count == 0

# Total routers across all networks
sum(netbird_network_routers_count)

# Total resources across all networks
sum(netbird_network_resources_count)

# Networks scrape error rate
rate(netbird_networks_scrape_errors_total[5m])

A comprehensive pre-built Grafana dashboard is available that provides visualizations for all NetBird API Exporter metrics.

1. Download the dashboard: Get grafana-dashboard.json from this repository
2. Import in Grafana: Go to Dashboards → Import and upload the JSON file
3. Configure data source: Ensure your Prometheus data source is selected

The dashboard includes organized sections for:

• Overview: Key metrics summary (total peers, users, groups, networks)
• Peers: Connection status, OS distribution, geographic breakdown
• Users: Role distribution, status overview, service vs regular users
• Groups: Peer and resource counts per group
• DNS: Nameserver configurations and status
• Networks: Network information and resource distribution
• Performance: API response times and error rates

For detailed installation instructions, customization options, and troubleshooting, see the Grafana Dashboard Documentation.

If you prefer to create custom panels, here are some example configurations:

1. Authentication errors: Verify your NETBIRD_API_TOKEN is correct and has appropriate permissions
2. Connection errors: Check if the NetBird API URL is accessible from your network
3. Missing metrics: Ensure your NetBird account has peers registered

Check logs for debugging:

# Docker Compose
docker-compose logs netbird-api-exporter

# Docker
docker logs netbird-api-exporter

# Binary
# Logs are output to stdout

Set LOG_LEVEL=debug for more verbose output.

• Store your NetBird API token securely (use Docker secrets, Kubernetes secrets, etc.)
• Consider running the exporter in a private network
• Implement proper firewall rules to restrict access to the metrics endpoint
• Regularly rotate your API tokens

All releases include signed build provenance attestations for enhanced supply chain security. You can verify the authenticity of our artifacts using the GitHub CLI:

# Verify Docker image attestation
gh attestation verify oci://ghcr.io/matanbaruch/netbird-api-exporter:latest --owner matanbaruch

# Download and verify binary attestations
gh run download --repo matanbaruch/netbird-api-exporter --name netbird-api-exporter-binaries-[VERSION]
gh attestation verify netbird-api-exporter-linux-amd64 --owner matanbaruch

For complete security documentation, see SECURITY.md.

See CHANGELOG.md for a detailed list of changes, new features, and bug fixes in each release.

• Go 1.23 or later
• golangci-lint (for linting)

go mod download
go build -o netbird-api-exporter

This project uses several tools to maintain code quality:

Set up pre-commit hooks to automatically run formatting, linting, and tests before each commit:

make setup-precommit

This provides two options:

• Simple Git Hook: Basic bash script (no external dependencies)
• Pre-commit Framework: Advanced hook management with additional checks

For quick setup with the simple git hook:

make install-hooks

See the Pre-commit Hooks Guide for detailed setup instructions and configuration options.

Run linting checks:

make lint

This runs:

• golangci-lint - Comprehensive Go linting
• go vet - Go's built-in static analysis
• gofmt - Code formatting check

Format code:

make fmt

Run tests and linting together:

make check

make help

Shows all available targets including:

• build - Build the binary
• test - Run tests
• lint - Run linting checks
• fmt - Format code
• check - Run all checks (tests + linting)

The project includes GitHub Actions workflows that automatically:

• Run linting checks on all pull requests
• Verify code formatting
• Run tests
• Check for security issues

go test ./...