BlackCraft Exporter
A 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 PyPI
BlackCraft Exporter is available on PyPI: blackcraft_exporter as a regular python package. It requires Python >= 3.11 to run
You can install it with pipx:
pipx install blackcraft_exporter
Then you should be able to run it using the blackcraft_exporter command (make sure your pipx binary $PATH has been set correctly)
$ blackcraft_exporter --version
BlackCraft Exporter v0.1.8
$ blackcraft_exporter
41832 2025-03-16 09:10:18.367 - INFO: Starting BlackCraft Exporter v0.1.7
41832 2025-03-16 09:10:18.367 - INFO: Started server process [41832]
41832 2025-03-16 09:10:18.368 - INFO: Waiting for application startup.
41832 2025-03-16 09:10:18.368 - INFO: Application startup complete.
41832 2025-03-16 09:10:18.368 - INFO: Uvicorn running on http://0.0.0.0:9165 (Press CTRL+C to quit)
with docker
BlackCraft Exporter is available on DockerHub: fallenbreath/blackcraft_exporter
docker run --rm -p 9165/tcp fallenbreath/blackcraft_exporter
manual installation
- Install poetry
- Get the repository, run
poetry installinside - 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
curl http://localhost:9165/probe?type=java&target=mc.example.com
Query parameters:
type: The type of the Minecraft server. Options:java,bedrocktarget: The address to the Minecraft servertimeout: (optional) The maximum request timeout in seconds, including all steps inside probing. Default:10mimic: (optional, java only) Override the hostname and port in the handshake packet. By default, thetargetparameter will be usedproxy: (optional, java only) If provided, connect to the server using the given proxy address- Supported http, socks4, socks5 proxy. See the python-socks library for more information
- The address syntax is something like
http://127.0.0.1:1081orsocks5://user:password@127.0.0.1:1080
max_attempts: (optional) The maximum probe attempts, including retries. Note that each attempt has the timeout oftimeout / max_attempts. Default:1
Prometheus
Example config for Minecraft Java Edition:
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
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
Metadata
Release files for blackcraft_exporter 0.1.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| blackcraft_exporter-0.1.8.tar.gz | 19.5 kB | Without provenance | Details for blackcraft_exporter-0.1.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| blackcraft_exporter-0.1.8-py3-none-any.whl | Python 3 | none | any | Details for blackcraft_exporter-0.1.8-py3-none-any.whl |
Total release size: 42.9 kB
Release files / blackcraft_exporter-0.1.8.tar.gz
| Download URL | blackcraft_exporter-0.1.8.tar.gz |
|---|---|
| Size | 19.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
747f5273c1bf93eb2d59dc74f06b781ead10f222e7cc9f118794af69ad420ea5
|
|
BLAKE2b-256 checksum How to use checksums |
8bdc64202c6415e91b0eb210ae640bbe3a965652af217f156df1f65176f4925f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.18 Linux/7.0.0-1019-azure
|
Release files / blackcraft_exporter-0.1.8-py3-none-any.whl
| Download URL | blackcraft_exporter-0.1.8-py3-none-any.whl |
|---|---|
| Size | 23.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a09c62662095a289f8dd042e411c70ee84b967ffd0f39622dd9bf6554a5cd839
|
|
BLAKE2b-256 checksum How to use checksums |
83c17ed8dca8ae8ca4f2b51dffb18d0c049456791d533f5d854f08a85b24e666
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.11.18 Linux/7.0.0-1019-azure
|
Security for blackcraft_exporter 0.1.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.