hteppl/x-ui-exporter repository overview

⁠3X-UI Metrics Exporter

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

⁠Features

• Online Monitoring: Tracks the number of online users across your 3X-UI instance.
• Traffic Metrics: Monitors total uploaded and downloaded bytes per client or inbound.
• 3X-UI Monitoring: Provides detailed XRay version information and additional operational metrics from 3X-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, .env files, and command-line arguments, 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 3X-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

3X-UI Metrics Exporter exposes thirteen Prometheus gauges covering online users, per-client and per-inbound traffic, Xray health, and panel diagnostics.

See METRICS.md⁠ for the complete reference — every metric name, type, and label, along with example PromQL queries and the gauge-semantics caveats that matter when querying byte totals.

⁠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.

⁠Configuration

3X-UI Metrics Exporter is configured with environment variables, which can be supplied directly or through a .env file. Every variable also has an equivalent command-line argument.

Below is a table of configuration options:

⁠Env File Configuration

The exporter loads a .env file from its working directory on startup. A sample with every option and its default is provided as .env.sample⁠:

cp .env.sample .env

# 3X-UI panel connection details (required)
PANEL_BASE_URL=https://your-panel-url
PANEL_USERNAME=your-panel-username
PANEL_PASSWORD=your-panel-password

# General settings
UPDATE_INTERVAL=30
TIMEZONE=UTC

# Metrics server configuration
METRICS_IP=0.0.0.0
METRICS_PORT=9090

Set ENV_FILE to load the file from another location:

ENV_FILE=/etc/x-ui-exporter/.env ./x-ui-exporter

Values are applied in order of increasing precedence: the .env file, then real environment variables, then command-line arguments. A variable already exported in the environment (or set by Docker or systemd) overrides the file, and a flag overrides both.

⁠Installation

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

⁠Docker (Recommended)

Running with Docker is the recommended way to deploy the exporter: it needs no toolchain on the host, isolates the exporter from the rest of your system, and makes updates a single pull away.

⁠Using Docker Compose:

A ready-to-use docker-compose.yml⁠ is provided with the project. It reads its configuration from a .env file, so copy the provided sample and fill in your panel details:

cp .env.sample .env

Then run:

docker compose up -d

⁠Automatic Installation Script

If you would rather run the exporter directly on the host under systemd, an installation script is available:

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

During installation, you'll be prompted to enter:

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

The script installs the binary to /usr/local/bin, writes your settings to /etc/x-ui-exporter/.env, and registers a systemd service. 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 an env file:

1. Create a .env file based on .env.sample⁠
2. Run the exporter from the same directory:

cp .env.sample .env
./x-ui-exporter

⁠Development

⁠Building from Source

Requires Go 1.27 or newer:

go build -o x-ui-exporter .
go test ./...

⁠Building the Docker Image

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 hteppl/x-ui-exporter:latest .

⁠Contribute

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

⁠Credits

Maintained by @hteppl⁠, with contributions from:

• @fffedor⁠
• @ksusonic⁠
• @welcomereality⁠

⁠License

This project is licensed under the GNU Affero General Public License v3.0. See the LICENSE⁠ file for the full text.