NetBird API Exporter

A Prometheus exporter for NetBird API that provides comprehensive metrics about your NetBird network peers, groups, users, networks, and DNS configuration.

Get started now View it on GitHub

What is NetBird API Exporter?

The NetBird API Exporter is a lightweight Prometheus exporter that fetches metrics from the NetBird REST API and exposes them in Prometheus format. It provides detailed insights into:

  • Peer Metrics: Connection status, operating systems, geographic distribution, and accessibility
  • Group Metrics: Group sizes, resource distribution, and management statistics
  • User Metrics: User roles, statuses, permissions, and activity
  • DNS Metrics: Nameserver groups, domains, and DNS configuration
  • Network Metrics: Network topology, routers, resources, and policies

Features

✅ Comprehensive Metrics: 40+ different metrics covering all aspects of your NetBird deployment
✅ Multiple Deployment Options: Docker, Docker Compose, Helm, systemd, or native binary
✅ Prometheus Integration: Native Prometheus metrics format with proper labels
✅ High Performance: Efficient API calls with error handling and recovery
✅ Security Focused: Minimal privileges and secure defaults
✅ Easy Configuration: Simple environment variable configuration
✅ Health Monitoring: Built-in health checks and self-monitoring metrics

Quick Start

Prerequisites

  • NetBird API token (how to get one)
  • Prometheus server or compatible metrics collection system

1. Get Your API Token

  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 for configuration

2. Choose Your Deployment Method

Pick the deployment method that works best for your environment:

Method Best For Complexity
Docker Compose Development & Testing ⭐ Easy
Docker Container Environments ⭐⭐ Medium
Helm Kubernetes Clusters ⭐⭐ Medium
systemd Linux Servers ⭐⭐⭐ Advanced
Binary Custom Setups ⭐⭐⭐ Advanced

3. Configure Prometheus

Add the exporter to your Prometheus configuration:

scrape_configs:
  - job_name: 'netbird-api-exporter'
    static_configs:
      - targets: ['localhost:8080']  # Update with your exporter address
    scrape_interval: 30s
    metrics_path: /metrics

4. Start Monitoring

Once running, you can:

  • View metrics at http://localhost:8080/metrics
  • Check health at http://localhost:8080/health
  • Create Grafana dashboards with the example queries

Architecture

The exporter is built with a modular architecture that makes it easy to extend and maintain:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   NetBird API   │◄───│  API Exporters   │◄───│   Prometheus    │
│                 │    │                  │    │                 │
│ • Peers         │    │ • Peers          │    │ • Scraping      │
│ • Groups        │    │ • Groups         │    │ • Storage       │
│ • Users         │    │ • Users          │    │ • Querying      │
│ • DNS           │    │ • DNS            │    │ • Alerting      │
│ • Networks      │    │ • Networks       │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Learn more about the architecture and available metrics.

Need Help?

  • 📖 Documentation: Browse the complete documentation in the sidebar
  • 🐛 Issues: Report bugs on GitHub Issues
  • 💡 Discussions: Ask questions in GitHub Discussions
  • 📧 Contact: Reach out to the maintainers

Contributing

We welcome contributions! See our Contributing Guide for details on:

  • Code of Conduct
  • Development setup
  • Submitting pull requests
  • Reporting issues

License

This project is licensed under the MIT License - see the LICENSE file for details.