Self Hosting

Overview

If you prefer to own your metrics pipeline end-to-end, Bitping’s open-source distributed-metrics tool lets you collect the same distributed monitoring data and export it as Prometheus metrics on your own infrastructure.

Checks still run from Bitping’s global node network, but the data flows into your Prometheus and Grafana stack instead of the hosted dashboard.

Prerequisites

A Bitping Developer account
An API key from the Bitping Developer Portal
Docker and Docker Compose (recommended), or a supported OS for the native binary

Installation

Docker Compose (Recommended)

Create a docker-compose.yaml:

version: '3'

services:
  distributed-metrics:
    image: bitping/distributed-metrics
    ports:
      - "3000:3000"
    environment:
      - BITPING_API_KEY=your_api_key_here
    volumes:
      - ./Metrics.yaml:/app/Metrics.yaml
    restart: unless-stopped

Then start it:

docker-compose up -d

Metrics are exposed at http://localhost:3000/metrics in Prometheus text format.

Shell Script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/BitpingApp/distributed-metrics/releases/latest/download/distributed-metrics-installer.sh | sh

Homebrew (macOS)

brew install BitpingApp/tap/distributed-metrics

Then run with your API key:

BITPING_API_KEY=your_api_key_here distributed-metrics

Configuration

Create a Metrics.yaml file to define what you want to monitor. The format is the same as the hosted metrics YAML configuration.

metric_clear_timeout: 1s

dns:
  - endpoint: example.com
    frequency: 30s
    residential: required
    proxy: denied

icmp:
  - endpoint: bitping.com
    frequency: 1m

hls:
  - endpoint: https://stream.example.com/live/master.m3u8
    frequency: 5m
    country: USA

Supported Protocols

Protocol	Description
HTTP	Website and API response time, success rate, status codes
DNS	Resolution performance and reliability (IP, MX, NS, TXT, SOA, SRV, TLSA)
ICMP	Ping latency and packet loss
HLS	Live video stream quality and buffering

Network Filtering

Each metric supports the same geographic and network filters as the hosted version:

Filter	Example
`country`	`USA`, `GBR`, `DEU`
`continent`	`EU`, `NA`, `AS`
`isp`	Regex pattern, e.g., `Comcast`
`mobile`	`allowed`, `denied`, `required`
`proxy`	`allowed`, `denied`, `required`
`residential`	`allowed`, `denied`, `required`

Prometheus Integration

Add the metrics endpoint to your Prometheus scrape config:

scrape_configs:
  - job_name: 'distributed-metrics'
    static_configs:
      - targets: ['localhost:3000']

Grafana Dashboards

Once Prometheus is scraping the metrics, add it as a data source in Grafana and build dashboards using the standard PromQL queries. The metrics follow the same naming conventions as the hosted platform, so any PromQL expressions from the hosted dashboards work directly.

Hosted vs Self-Hosted

Feature	Hosted	Self-Hosted
Setup	Instant, no infrastructure	Requires Prometheus + Grafana
Protocols	HTTP, DNS, ICMP, HLS	HTTP, DNS, ICMP, HLS
Dashboards	Built-in with geo maps	Bring your own Grafana
Alerting	Built-in with email + webhook	Use Prometheus Alertmanager
Data ownership	Managed by Bitping	Fully yours
Maintenance	Zero	You manage the stack

Customers

Nodes