Configuration

Configuration

TraceBullet stores its config at config/tracebullet-server.toml on the server (or client for singleplayer). The file is created with defaults on first launch.

Restart requirements are noted per-section:

• World restart — stop and start the server (or unload and reload the world). A simple /reload is not sufficient.
• Game restart — full server process stop + start.

[otel] — OpenTelemetry Export

Requires world restart to take effect.

Key	Type	Default	Description
url	string	""	Base URL of the OTLP HTTP endpoint. Leave empty to disable all export. TraceBullet appends /v1/metrics to this value. Must be a valid URL if set. Example: "http://localhost:4318"
auth	string	""	Value for the HTTP Authorization header. Must begin with Bearer or Basic if non-empty. Leave empty for unauthenticated access.
service_name_override	string	""	Overrides the service.name OTel resource attribute. Defaults to the Minecraft world (level) name when empty. Useful when multiple servers share a world name or when you want a stable identifier independent of the level name.
custom_attributes	list of strings	[]	Additional OTel resource attributes attached to every exported metric. Each entry must be a key=value string.

Examples

Minimal — local collector, no authentication:

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

Remote collector with Bearer token and extra resource attributes:

[otel]
url                   = "https://collector.example.com"
auth                  = "Bearer eyJhbGciOiJSUzI1NiJ9..."
service_name_override = "survival-main"
custom_attributes     = ["modpack.version=2.1.0", "environment=production"]

[threading] — Background Thread Pool

Requires game restart to take effect.

Key	Type	Default	Range	Description
schedule_thread_pool_size	integer	availableProcessors × 0.25 (minimum 1)	1–32	Size of the background scheduled thread pool used for polling metrics on a timer. The default is calculated at startup. On a 4-core machine this is 1; on a 16-core machine it is 4. Increase if you observe metric gaps under heavy server load.

[metrics] — Per-Group Enable/Disable Flags

All keys default to true. Requires game restart to take effect.

Key	Default	Controls
tps	true	TPS gauge and tick time histogram
player	true	Player count gauge and latency distribution gauge
world_chunk	true	Loaded and force-loaded chunk count gauges; chunk load/unload event counters
entity	true	Living entity count gauge per chunk and entity type
jvm	true	JVM heap memory gauges, GC counters, CPU load gauge, thread count gauge
block_entity	true	Block entity count gauge per chunk and type
item_entity	true	Dropped item entity count gauge per chunk and item type
world_save	true	World save duration histogram
scheduled_tick	true	Pending scheduled block and fluid tick queue size gauges
chunk_generation	true	Newly generated (not disk-loaded) chunk counter

Disabling expensive metrics

entity, block_entity, and item_entity perform per-chunk entity iteration every minute and generate the highest metric cardinality. On very large servers or modpacks with many entity types, disable them if they cause noticeable overhead:

[metrics]
entity       = false
block_entity = false
item_entity  = false

Full default config

[otel]
# OTLP HTTP base URL — leave empty to disable export
url = ""
# Authorization header value — must start with "Bearer" or "Basic"
auth = ""
# Override service.name resource attribute (defaults to world name)
service_name_override = ""
# Extra resource attributes as key=value strings
custom_attributes = []

[threading]
# Background scheduler thread pool size (default: availableProcessors * 0.25, range 1–32)
schedule_thread_pool_size = 1

[metrics]
tps              = true
player           = true
world_chunk      = true
entity           = true
jvm              = true
block_entity     = true
item_entity      = true
world_save       = true
scheduled_tick   = true
chunk_generation = true

The actual default for schedule_thread_pool_size depends on your hardware and will differ from the 1 shown above.