Metadata-Version: 2.3
Name: blackcraft_exporter
Version: 0.1.3
Summary: A blackbox_exporter-like prober for Minecraft
License: GPLv3
Author: Fallen_Breath
Requires-Python: >=3.11,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: dnspython (>=2.7.0,<3.0.0)
Requires-Dist: fastapi (>=0.115.8,<0.116.0)
Requires-Dist: mcstatus (>=11.1.1,<12.0.0)
Requires-Dist: prometheus-client (>=0.21.1,<0.22.0)
Requires-Dist: pydantic (>=2.10.6,<3.0.0)
Requires-Dist: pydantic-settings (>=2.7.1,<3.0.0)
Requires-Dist: python-socks[asyncio] (>=2.7.1,<3.0.0)
Requires-Dist: uvicorn[standard] (>=0.34.0,<0.35.0)
Description-Content-Type: text/markdown

# BlackCraft Exporter

[![License](https://img.shields.io/github/license/Fallen-Breath/blackcraft_exporter.svg)](http://www.gnu.org/licenses/gpl-3.0.html)
[![Issues](https://img.shields.io/github/issues/Fallen-Breath/blackcraft_exporter.svg)](https://github.com/Fallen-Breath/blackcraft_exporter/issues)
[![Docker](https://img.shields.io/docker/v/fallenbreath/blackcraft_exporter/latest)](https://hub.docker.com/r/fallenbreath/blackcraft_exporter)

A [blackbox_exporter](https://github.com/prometheus/blackbox_exporter)-like prober for Minecraft

## To run

BlackCraft Exporter requires no configuration file and can be started with no extra argument.

By default, it will listen on tcp `0.0.0.0:9165`. Run with `--help` argument to see all available CLI arguments

### with pip

TODO

### with docker

BlackCraft Exporter is available in DockerHub: [fallenbreath/blackcraft_exporter](https://hub.docker.com/r/fallenbreath/blackcraft_exporter)

```bash
docker run --rm -p 9165/tcp fallenbreath/blackcraft_exporter
```

### manual installation

1. Install [poetry](https://python-poetry.org/)
2. Get the repository, run `poetry install` inside
3. Run `python -m blackcraft_exporter`

## To use

### Basic usage

Just like the blackbox exporter, you need to send an HTTP GET request to the `/probe` endpoint
to get the metrics of the target Minecraft server

```bash
curl http://localhost:9165/probe?type=java&target=mc.example.com
```

Query parameters:

- `type`: The type of the Minecraft server. Options: `java`, `bedrock`
- `target`: The address to the Minecraft server
- `timeout`: (optional) The maximum request timeout in seconds, including all steps inside probing. Default: `10`
- `mimic`: (optional, java only) Override the hostname and port in the handshake packet. By default, the `target` parameter will be used
- `proxy`: (optional, java only) If provided, connect to the server using the given proxy address
  - Supported http, socks4, socks5 proxy. See the [python-socks](https://github.com/romis2012/python-socks) library for more information
  - The address syntax is something like `http://127.0.0.1:1081` or `socks5://user:password@127.0.0.1:1080`
- `max_attempts`: (optional) The maximum probe attempts, including retries. Note that each attempt has the timeout of `timeout / max_attempts`. Default: `1`

### Prometheus

Example config for Minecraft Java Edition:

```yml
scrape_configs:
  - job_name: blackcraft          # Can be any name you want
    metrics_path: /probe
    params:
      type: [ java ]                # Set type to java
    static_configs:
      - targets:
        - 192.168.1.1             # IP only
        - 192.168.1.1:25566       # IP with port
        - mc.example.com          # Hostname only. SRV is supported
        - mc.example.com:25566    # Hostname with port
    relabel_configs:
      - source_labels: [ __address__ ]
        target_label: __param_target
      - target_label: __address__
        replacement: localhost:9165  # Your BlackCraft Exporter's hostname:port
```

Example config with more flexible control on the targets

```yml
scrape_configs:
  - job_name: blackcraft          # Can be any name you want
    metrics_path: /probe
    static_configs:
      - targets:
        - labels: 
            instance: 'My Java Server'  # Its disabled name in grafana
            type: 'java'
          targets: [ 'mc.example.com' ]
        - labels: 
            instance: 'My Bedrock Server'
            type: 'bedrock'
          targets: [ 'bedrock.example.com:25566' ]
    relabel_configs:
      - source_labels: [ type ]  # maps the "type" label into the query parameter
        target_label: __param_type
      - source_labels: [ __address__ ]
        target_label: __param_target
      - target_label: __address__
        replacement: localhost:9165  # Your BlackCraft Exporter's hostname:port
```

### Grafana

Example dashboard for BlackCraft Exporter: https://grafana.com/grafana/dashboards/22915

