Skip to main content

BlackCraft Exporter

License Issues PyPI Version Docker

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

  1. Install poetry
  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

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 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:

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)

Source distribution for blackcraft_exporter 0.1.8
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)

Table of built distributions (wheels) for blackcraft_exporter 0.1.8
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page