sedyh/x-ui-exporter repository overview

⁠X-UI Metrics Exporter

X-UI Metrics Exporter is a simple tool designed to collect and export metrics from the Original X-UI Web Panel⁠. This exporter provides some monitoring capabilities for various aspects of your X-UI, including node status, traffic flow, system performance, and user activity, making all data readily available for integration with the Prometheus monitoring system.

This is the fork of 3X-UI Metrics Exporter⁠ which is made by hteppl⁠. It was moddified to support the legacy panel versions.

⁠Features

• Online Monitoring: Tracks the number of online users across your X-UI instance.
• Traffic Metrics: Monitors total uploaded and downloaded bytes per client or inbound.
• X-UI Monitoring: Provides detailed XRay version information and additional operational metrics from X-UI.
• Version and Start Time Information: Delivers core version information and confirms whether the core service has started successfully.
• Flexible Configuration Options: Supports customization through environment variables, command-line arguments, and YAML configuration files, providing maximum flexibility for different deployment scenarios.
• Multi-Architecture Support: Features Docker images for multiple architectures, including AMD64 and ARM64, ensuring compatibility across diverse deployment environments.
• Enhanced Security: Offers optional BasicAuth protection for the metrics endpoint, providing an additional layer of security for sensitive monitoring data.
• Seamless Prometheus Integration: Designed to work flawlessly with Prometheus, enabling straightforward setup and configuration for comprehensive X-UI panel monitoring.
• Comprehensive VPN Monitoring: Simplifies the monitoring and management of VPN services by providing a rich set of metrics, significantly improving visibility into system performance and user activity.

⁠Metrics

Below is a table of the metrics provided by X-UI Metrics Exporter.

⁠Users

Users metrics, such as online:

⁠Clients

Clients metrics (params: id, email):

⁠Inbounds

Inbounds metrics (params: id, remark):

⁠System

System metrics (version param for x_ui_xray_version):

⁠Configuration

X-UI Metrics Exporter can be configured using environment variables, command-line arguments, or a YAML configuration file. These are alternative methods of configuration, and you should choose one approach for your deployment.

Below is a table of configuration options:

⁠YAML Configuration

You can use a YAML configuration file to configure the exporter by providing the --config-file flag. When using a configuration file, all settings are read from the file and any command-line arguments are ignored. The YAML configuration file should contain the same parameters as the command-line arguments, but in YAML format.

A sample configuration file config-example.yaml is provided with the project, which you can use as a template for your own configuration. The structure of the YAML file matches the command-line arguments.

Example YAML configuration:

# X-UI panel connection details
panel-base-url: "https://your-panel-url"
panel-username: "your-panel-username"
panel-password: "your-panel-password"
insecure-skip-verify: false

# General settings
update-interval: 30
timezone: "UTC"

# Metrics server configuration
metrics-ip: "0.0.0.0"
metrics-port: 9090
clients-bytes-rows: 0
metrics-protected: false
metrics-username: "metricsUser"
metrics-password: "MetricsVeryHardPassword"

⁠Installation

There are several ways to install and run the X-UI Metrics Exporter, each tailored to different environments and deployment preferences. Select the installation method that aligns best with your infrastructure requirements:

⁠Automatic Installation Script (Recommended)

The easiest way to install the exporter is using automatic installation script:

bash <(curl -fsSL raw.githubusercontent.com/sedyh/x-ui-exporter/main/install.sh)

During installation, you'll be prompted to enter:

1. Your X-UI panel URL
2. Admin username
3. Admin password

After installation, the service will be running automatically. You can manage it with:

sudo systemctl status x-ui-exporter    # Check status
sudo systemctl restart x-ui-exporter   # Restart service
sudo systemctl stop x-ui-exporter      # Stop service

⁠Manual CLI Installation

If you prefer manual installation, download the latest binary from the releases page⁠ for your architecture.

⁠Running with command-line arguments:

./x-ui-exporter --panel-base-url="https://your-panel-url" \
                --panel-username="your-panel-username" \
                --panel-password="your-panel-password"

⁠Running with a configuration file:

1. Create a config.yaml file based on the example configuration
2. Run the exporter:

./x-ui-exporter --config-file=config.yaml

⁠Docker Installation

Running with Docker provides an optimal solution for containerized environments, offering simplified deployment and streamlined updates.

⁠Using Docker Run:

docker run -d \
  --name x-ui-exporter \
  -e PANEL_BASE_URL="https://your-panel-url" \
  -e PANEL_USERNAME="your-panel-username" \
  -e PANEL_PASSWORD="your-panel-password" \
  -p 9090:9090 \
  sedyh/x-ui-exporter

⁠Using Docker Compose:

Create a docker-compose.yml file:

version: "3"
services:
  x-ui-exporter:
    image: sedyh/x-ui-exporter
    container_name: x-ui-exporter
    restart: unless-stopped
    environment:
      - PANEL_BASE_URL=https://your-panel-url
      - PANEL_USERNAME=your-panel-username
      - PANEL_PASSWORD=your-panel-password
      # Optional settings
      # - METRICS_PORT=9090
      # - UPDATE_INTERVAL=30
    ports:
      - "9090:9090"

Then run:

docker-compose up -d

⁠Docker build

You can build the Docker image locally for both AMD and ARM architectures using Docker Buildx:

docker buildx create --name multiarch-builder --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --build-arg GIT_TAG=$(git describe --tags --always) \
  --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
  -t <registry_name>:<tag> \
  --push .

⁠Building for a Single Architecture

To build for a specific architecture only:

docker buildx build --platform linux/amd64 -t ksusonic/x-ui-exporter:latest .

⁠Integration with Prometheus

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

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

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

⁠Contribute

Contributions to X-UI 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.