Skip to content

kutovoys/marzban-exporter

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

31 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Marzban Metrics Exporter

GitHub Release GitHub Actions Workflow Status DockerHub GitHub License

Marzban Metrics Exporter is an application designed to collect and export metrics from the Marzban VPN management panel. This exporter enables monitoring of various aspects of the VPN service, such as node status, traffic, system metrics, and user information, making the data available for the Prometheus monitoring system.

Features

  • Node Status Monitoring: Tracks the connection status of VPN nodes, indicating whether each node is connected or not.
  • Traffic Metrics: Provides detailed metrics on uplink and downlink traffic for each VPN node.
  • System Health Monitoring: Reports on system health indicators such as total and used memory, CPU cores, CPU usage, total number of users, active users, and bandwidth metrics.
  • User Activity Tracking: Monitors user activity, including data limits, used traffic, lifetime used traffic, and online status within the last 2 minutes.
  • Version and Start Time Information: Includes core version information and whether the core service has started successfully.
  • Configurable via Environment Variables and Command-line Arguments: Allows customization and configuration through both environment variables and command-line arguments, making it easy to adjust settings.
  • Support for Multiple Architectures: Docker images are available for multiple architectures, including AMD64 and ARM64, ensuring compatibility across various deployment environments.
  • Optional BasicAuth Protection: Provides the option to secure the metrics endpoint with BasicAuth, adding an additional layer of security.
  • Integration with Prometheus: Designed to integrate seamlessly with Prometheus, facilitating easy setup and configuration for monitoring Marzban VPN services.
  • Simplifies VPN Monitoring: By providing a wide range of metrics, it simplifies the process of monitoring and managing VPN services, enhancing visibility into system performance and user activity.

Metrics

Below is a table of the metrics provided by Marzban Metrics Exporter:

Name Description
marzban_nodes_status Status of Marzban nodes (1 for connected, 0 otherwise).
marzban_nodes_uplink Uplink traffic of Marzban nodes.
marzban_nodes_downlink Downlink traffic of Marzban nodes.
marzban_user_data_limit Data limit of the user.
marzban_user_used_traffic Used traffic of the user.
marzban_user_lifetime_used_traffic Lifetime used traffic of the user.
marzban_user_expiration_date User's subscription expiration date
marzban_user_online Whether a user is online within the last 2 minutes.
marzban_core_started Indicates if the core is started (1) or not (0).
marzban_panel_mem_total Total memory.
marzban_panel_mem_used Used memory.
marzban_panel_cpu_cores Number of CPU cores.
marzban_panel_cpu_usage CPU usage percentage.
marzban_panel_total_users Total number of users.
marzban_panel_users_active Number of active users.
marzban_all_incoming_bandwidth Incoming bandwidth.
marzban_all_outgoing_bandwidth Outgoing bandwidth.
marzban_panel_incoming_bandwidth_speed Incoming bandwidth speed.
marzban_panel_outgoing_bandwidth_speed Outgoing bandwidth speed.

Configuration

Marzban Metrics Exporter can be configured using environment variables or command-line arguments. When both are provided, command-line arguments take precedence.

Below is a table of configuration options:

Variable Name Command-Line Argument Required Default Value Description
MARZBAN_BASE_URL --marzban-base-url No https://<your-marzban-url> URL of the Marzban management panel.
MARZBAN_USERNAME --marzban-username Yes <your-marzban-username> Username for the Marzban panel.
MARZBAN_PASSWORD --marzban-password Yes <your-marzban-password> Password for the Marzban panel.
MARZBAN_SOCKET --marzban-socket No <your-marzban-socket-path> Path to Marzban Unix Domain Socket.
METRICS_PORT --metrics-port No 9090 Port for the metrics server.
METRICS_PROTECTED --metrics-protected No false Enable BasicAuth protection for metrics endpoint.
METRICS_USERNAME --metrics-username No metricsUser Username for BasicAuth, effective if METRICS_PROTECTED is true.
METRICS_PASSWORD --metrics-password No MetricsVeryHardPassword Password for BasicAuth, effective if METRICS_PROTECTED is true.
UPDATE_INTERVAL --update-interval No 30 Interval (in seconds) for metrics update.
TIMEZONE --timezone No UTC Timezone for correct time display.
INACTIVITY_TIME --inactivity-time No 2 Time (in minutes) to determine user activity.

Usage

CLI

/marzban-exporter --marzban-base-url=<your-marzban-panel-url> --marzban-username=<your-marzban-username> --marzban-password=<your-marzban-password>

Docker

docker run -d \
  -e MARZBAN_BASE_URL=<your-marzban-panel-url> \
  -e MARZBAN_USERNAME=<your-marzban-username> \
  -e MARZBAN_PASSWORD=<your-marzban-password> \
  -p 9090:9090 \
  kutovoys/marzban-exporter

Docker Compose

version: "3"
services:
  marzban-exporter:
    image: kutovoys/marzban-exporter
    environment:
      - MARZBAN_BASE_URL=<your-marzban-panel-url>
      - MARZBAN_USERNAME=<your-marzban-username>
      - MARZBAN_PASSWORD=<your-marzban-password>
    ports:
      - "9090:9090"

Integration with Prometheus

To collect metrics with Prometheus, add the exporter to your prometheus.yml configuration file:

scrape_configs:
  - job_name: "marzban_exporter"
    static_configs:
      - targets: ["<exporter-ip>:9090"]

Ensure to replace <your-marzban-panel-url>, <your-marzban-username>, <your-marzban-password>, and <exporter-ip> with your actual information.

TODO

  • ✅ Ensure all necessary environment variables are set and validate them at startup.
  • ✅ Implement command line arguments for passing configuration options.
  • ⏳ Create a Grafana dashboard tailored for the Marzban Metrics Exporter to visualize the collected metrics effectively.

Contribute

Contributions to Marzban Metrics Exporter are warmly welcomed. Whether it's bug fixes, new features, or documentation improvements, your input helps make this project better. Here's a quick guide to contributing:

  1. Fork & Branch: Fork this repository and create a branch for your work.
  2. Implement Changes: Work on your feature or fix, keeping code clean and well-documented.
  3. Test: Ensure your changes maintain or improve current functionality, adding tests for new features.
  4. Commit & PR: Commit your changes with clear messages, then open a pull request detailing your work.
  5. Feedback: Be prepared to engage with feedback and further refine your contribution.

Happy contributing! If you're new to this, GitHub's guide on Creating a pull request is an excellent resource.