GitHub

VMProber

VMProber Documentation

Welcome to the VMProber documentation. VMProber is a high-performance Go application for comprehensive network and service monitoring. It supports TCP, UDP, ICMP, HTTP/HTTPS, DNS, and gRPC probes with both pull (Prometheus) and push (VictoriaMetrics) modes for exporting metrics.

VMProber Logo

Quick Navigation

📚 Getting Started

Start here if you’re new to VMProber:

Guide Description
Installation How to install and build VMProber
Quick Start Get up and running in 5 minutes
Configuration Understanding configuration files
Basic Usage Your first probes and metrics

🏗️ Architecture

Understand how VMProber works under the hood:

Topic Description
System Overview High-level system architecture
Design Principles Architectural decisions and patterns

🔧 Components

Deep dive into VMProber components:

Component Description
Probe System TCP, UDP, ICMP, HTTP/HTTPS, DNS, and gRPC probes

🚀 Operations

Deploy and operate VMProber in production:

Guide Description
Deployment Docker, Kubernetes, systemd
Docker Guide Container deployment details
Troubleshooting Common issues and solutions

👨‍💻 Development

For contributors and developers:

Topic Description
Development Setup Environment and tooling
E2E Testing End-to-end testing guide

📖 Reference

API and technical reference:

Reference Description
API Reference HTTP API endpoints
Metrics Reference All exported metrics

📘 Guides

Step-by-step tutorials for common tasks:

Guide Description
Monitoring Setup Setting up Prometheus/Grafana

Key Features

Feature Description
✅ Multi-protocol probes TCP, UDP, ICMP, HTTP/HTTPS, DNS, and gRPC support
✅ Dual export modes Pull (Prometheus) and Push (VictoriaMetrics)
✅ Reliability WAL system for fault tolerance
✅ Performance Efficient scheduling with rate limiting
✅ Observability Comprehensive metrics, logging, and profiling
✅ Production-ready Graceful shutdown, health checks, hot reload
✅ Modern Dashboard Real-time web interface

System Architecture

flowchart TB
    subgraph VMProber["VMProber"]
        subgraph Probes["Probe Layer"]
            TCP["TCP Probe"]
            UDP["UDP Probe"]
            ICMP["ICMP Probe"]
            HTTP["HTTP Probe"]
            DNS["DNS Probe"]
            gRPC["gRPC Probe"]
        end

        Scheduler["Scheduler"]

        Probes --> Scheduler

        Scheduler --> Normalizer["Normalizer"]
        Scheduler --> Metrics["Metrics Collector"]

        Normalizer --> WAL["WAL Buffer"]
        Metrics --> MetricsEndpoint["/metrics endpoint"]

        WAL --> VMAdapter["VM Push Adapter"]
    end

    Prometheus["Prometheus"] -.->|scrape| MetricsEndpoint
    VMAdapter -->|push| VictoriaMetrics["VictoriaMetrics"]

Quick Start Example

# config.yaml
listen:
  port: 8429
  host: "0.0.0.0"

pull:
  enabled: true

push:
  enabled: true
  endpoints:
    - url: "http://vminsert:8480/insert/0/prometheus/api/v1/import"

targets:
  static:
    # TCP probe
    - host: "example.com"
      port: 443
      proto: tcp
      interval: 30s

    # HTTPS health check
    - host: "api.example.com"
      port: 443
      proto: https
      interval: 30s
      http:
        method: GET
        path: /health
        expected_status_code: 200

    # DNS check
    - host: "8.8.8.8"
      port: 53
      proto: dns
      dns:
        query_name: "google.com"
        query_type: A

    # gRPC health check
    - host: "grpc.example.com"
      port: 50051
      proto: grpc
      grpc:
        service: "my.Service"
        expected_status: SERVING

# Run VMProber
./vmprober --config=config.yaml

# Check metrics
curl http://localhost:8429/metrics

Getting Help

Repository: github.com/gdagil/vmprober

VMProber