Skip to content

Getting Started

Jump to bottom
korti11 edited this page Jun 7, 2026 · 1 revision

Getting Started

This guide walks through installing TraceBullet and sending your first metrics to a collector. The minimal setup takes about five minutes if you already have Docker available.

Step 1 — Install the Mod

  1. Download the latest tracebullet-<version>.jar from the Releases page.
  2. Place the JAR in your server's mods/ folder.
  3. Start the server once. This generates the config file at config/tracebullet-server.toml with all defaults. The mod logs No OTel URL configured skipping setup. and otherwise runs normally.
  4. Stop the server.

Singleplayer / LAN: Place the JAR in your client's mods/ folder instead. The config file is generated the first time you load a world.

Step 2 — Set Up a Collector

Skip this step if you already have an OTLP-compatible endpoint and go straight to Step 3.

The quickest path is to run the OpenTelemetry Collector Contrib and push metrics directly into Prometheus using remote write.

Minimal collector config

Create a file named otel-collector-config.yaml:

receivers:
  otlp:
    protocols:
      http:
        endpoint: "0.0.0.0:4318"

exporters:
  prometheusremotewrite:
    endpoint: "http://localhost:9090/api/v1/write"

service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [prometheusremotewrite]

Run the collector with Docker

# Linux / macOS
docker run --rm -p 4318:4318 \
  -v $(pwd)/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml \
  otel/opentelemetry-collector-contrib:latest

# Windows PowerShell
docker run --rm -p 4318:4318 `
  -v "${PWD}/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml" `
  otel/opentelemetry-collector-contrib:latest

The collector is now accepting OTLP HTTP on http://localhost:4318 and writing directly to Prometheus.

Enable remote write in Prometheus

Start Prometheus with the --web.enable-remote-write-receiver flag so it accepts incoming writes:

prometheus --web.enable-remote-write-receiver

No additional scrape configuration is needed — the collector pushes metrics directly to Prometheus.

Import the Grafana dashboard

The repository includes a pre-built dashboard at dashboards/prometheus-dashboard.json. In Grafana: Dashboards → New → Import → Upload JSON file, then select the file.

Step 3 — Configure TraceBullet

Open config/tracebullet-server.toml. The only required change is setting url under [otel] to your collector's base URL:

[otel]
url = "http://localhost:4318"

Important: Do not append /v1/metrics to the URL — TraceBullet adds that path automatically.

Save the file and start the server. On a successful connection the mod logs Setup OTel exporter. during startup. Metrics begin flowing within the first export cycle (~60 seconds).

Restart requirements

Config section Requires
[otel] World restart (stop + start the server, or reload the world)
[threading] Game restart (full server process stop + start)
[metrics] Game restart

Step 4 — Verify

  1. Check the server log for Setup OTel exporter. — if present the mod connected successfully.
  2. In Prometheus, run a query for minecraft_server_tps (Prometheus converts . to _ in metric names). It should return data within the first export cycle.
  3. In Grafana, open the imported dashboard. Set the Server variable to your world name (this is the service.name value, which defaults to the world folder name). TPS, player count, and JVM heap populate within the first polling cycle (~1 minute).

Nothing appears after 2 minutes? Check:

  • The server can reach the collector on port 4318 (firewall / Docker networking)
  • The collector can reach Prometheus on port 9090
  • The URL in the config has no trailing slash and no /v1/metrics suffix
  • The config file was saved before the last server start

Step 5 — Optional: Secure the Connection

If your collector is not on localhost, add an Authorization header. The value must start with Bearer or Basic:

[otel]
url  = "https://collector.example.com"
auth = "Bearer eyJhbGciOiJSUzI1NiJ9..."

Other Backends

TraceBullet sends standard OTLP HTTP and works with any compatible receiver.

Backend Typical URL Notes
Grafana Alloy http://<host>:4318 Enable the otelcol.receiver.otlp component in your Alloy config
Dynatrace https://<env>.live.dynatrace.com/api/v2/otlp Use a Bearer API token with the metrics.ingest scope
Honeycomb https://api.honeycomb.io Use Bearer <API-KEY>
Any OTLP HTTP receiver Receiver base URL /v1/metrics is appended automatically

Tagging Multiple Servers

If you run multiple server instances sending to the same collector, each server is distinguishable by the service.name resource attribute (defaults to the world name). Override it or add extra tags to differentiate instances:

[otel]
url                   = "http://collector:4318"
service_name_override = "survival-us-east"
custom_attributes     = ["modpack.version=1.5.0", "region=us-east"]

See Configuration for the full list of options.

Clone this wiki locally