-
Notifications
You must be signed in to change notification settings - Fork 0
Metrics Reference
This page documents every metric exported by TraceBullet.
| Attribute key | Type | Example value | Present on |
|---|---|---|---|
service.name |
string | "survival" |
All metrics (OTel resource attribute) |
server.name |
string | "survival" |
All metrics |
dimension.name |
string | "minecraft:overworld" |
All world-scope metrics |
latency.range |
string | "0-49" |
minecraft.server.player.latency |
gc.name |
string | "G1 Young Generation" |
minecraft.server.jvm.gc.* |
entity.type |
string | "minecraft:zombie" |
minecraft.server.world.entity.living |
item.type |
string | "minecraft:diamond" |
minecraft.server.world.entity.item |
block_entity.type |
string | "minecraft:chest" |
minecraft.server.world.block_entity |
chunk.pos.x |
long | -32 |
Entity and block-entity chunk metrics |
chunk.pos.z |
long | 16 |
Entity and block-entity chunk metrics |
service.nameis an OTel resource attribute shared by all metrics exported in a session. It defaults to the Minecraft world name and can be overridden viaotel.service_name_overridein the config.server.nameis a metric attribute and carries the same value.
All metrics use cumulative aggregation temporality. The OTLP reader flushes approximately every 60 seconds (the SDK default for PeriodicMetricReader).
- Polled 1-min — TraceBullet's own scheduler samples and records the value on a ~60-second cycle.
- Event-driven — recorded immediately when the corresponding Minecraft event fires; still exported on the next OTLP flush.
Enabled by metrics.tps = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.tps |
DoubleGauge | tps |
Polled 1-min |
server.name, dimension.name
|
minecraft.server.tick_time |
DoubleHistogram | ms |
Polled 1-min |
server.name, dimension.name
|
Ticks per second for each dimension. The Minecraft server targets 20 TPS. Values consistently below 20 indicate lag.
Distribution of individual tick durations in milliseconds per dimension. Use this to compute p50, p95, and p99 tick latencies directly in your backend. Values above 50 ms mean the server is behind the 20 TPS target.
Histogram bucket boundaries (ms): 5, 10, 20, 30, 40, 50, 75, 100, 150, 200, 300, 500
Enabled by metrics.player = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.player.count |
LongGauge | {player} |
Polled 1-min | server.name |
minecraft.server.player.latency |
LongGauge | count |
Polled 1-min |
server.name, latency.range
|
Number of players currently connected.
Connected players grouped into latency buckets. Each latency.range value is always exported (the count may be 0).
latency.range |
Meaning |
|---|---|
"0-49" |
< 50 ms — excellent |
"50-149" |
50–149 ms — acceptable |
"150-299" |
150–299 ms — high |
"300+" |
≥ 300 ms — poor |
Enabled by metrics.jvm = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.jvm.memory.heap.used |
LongGauge | By |
Polled 1-min | server.name |
minecraft.server.jvm.memory.heap.committed |
LongGauge | By |
Polled 1-min | server.name |
minecraft.server.jvm.memory.heap.max |
LongGauge | By |
Polled 1-min | server.name |
minecraft.server.jvm.gc.collections |
LongCounter | {collection} |
Polled 1-min |
server.name, gc.name
|
minecraft.server.jvm.gc.pause_time |
LongCounter | ms |
Polled 1-min |
server.name, gc.name
|
minecraft.server.jvm.cpu.load |
DoubleGauge | 1 |
Polled 1-min | server.name |
minecraft.server.jvm.thread.count |
LongGauge | {thread} |
Polled 1-min | server.name |
used is the current allocation, committed is memory the JVM has obtained from the OS, and max is the JVM heap ceiling (-Xmx). All values are in bytes. A useful derived metric is heap utilization: used / max * 100.
gc.collections and gc.pause_time track deltas — each exported value is the increment since the previous poll, not a monotonically increasing total. They are only written when at least one GC collection occurred in the interval. The gc.name attribute identifies the GC pool (e.g., "G1 Young Generation", "G1 Old Generation").
Query note: Because these counters export deltas rather than a cumulative total, use the raw value directly in your backend rather than a
rate()function.
minecraft.server.jvm.cpu.load is the JVM process CPU load as a ratio between 0.0 (idle) and 1.0 (fully saturated). Multiply by 100 for a percentage. This value may not be available on all JVMs; TraceBullet skips the write if the value cannot be obtained.
Enabled by metrics.world_chunk = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.world.chunks.loaded |
LongGauge | {chunk} |
Polled 1-min |
server.name, dimension.name
|
minecraft.server.world.chunks.force_loaded |
LongGauge | {chunk} |
Polled 1-min |
server.name, dimension.name
|
minecraft.server.world.chunk.load |
LongCounter | {chunk} |
Event-driven |
server.name, dimension.name
|
minecraft.server.world.chunk.unload |
LongCounter | {chunk} |
Event-driven |
server.name, dimension.name
|
chunks.loaded and chunks.force_loaded reflect the current count at sample time. chunk.load and chunk.unload are cumulative event counters; use a rate function in your backend to get events per minute.
Enabled by metrics.chunk_generation = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.world.chunk.generated |
LongCounter | {chunk} |
Event-driven |
server.name, dimension.name
|
Counts only chunks newly generated during this session — chunks loaded from disk are not counted. A sustained generation rate indicates active exploration, which contributes to world-gen CPU load. Use this to correlate TPS dips with exploration events.
Enabled by metrics.entity = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.world.entity.living |
LongGauge | {entity} |
Polled 1-min |
server.name, dimension.name, entity.type, chunk.pos.x, chunk.pos.z
|
Each unique combination of dimension, entity type, chunk X, and chunk Z is a separate time series. On servers with many entity types this can produce a large number of series. Disable with metrics.entity = false if cardinality becomes a concern.
Enabled by metrics.item_entity = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.world.entity.item |
LongGauge | {entity} |
Polled 1-min |
server.name, dimension.name, item.type, chunk.pos.x, chunk.pos.z
|
Counts dropped item stacks on the ground per chunk and item type (not items in inventories or containers). Useful for detecting mob farm output accumulation or identifying cleanup pressure in high-traffic areas.
Enabled by metrics.block_entity = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.world.block_entity |
LongGauge | {block_entity} |
Polled 1-min |
server.name, dimension.name, block_entity.type, chunk.pos.x, chunk.pos.z
|
Only iterates chunks that are fully loaded and ready to send to clients. Partially-loaded chunks (those still in the generation pipeline) are excluded. Use this to spot TPS-heavy block entity concentrations such as large hopper networks or many furnaces.
Enabled by metrics.world_save = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.world.save.duration |
DoubleHistogram | ms |
Event-driven |
server.name, dimension.name
|
Histogram bucket boundaries (ms): 50, 100, 200, 500, 1000, 2000, 5000, 10000
Records the elapsed time from the start of a server tick to the completion of the save event for each dimension. The measurement includes normal tick execution overhead — expect a baseline of approximately 50 ms even on fast hardware. Values substantially above 100 ms suggest disk I/O pressure or large region files. Repeated spikes above 500 ms are a precursor to visible TPS degradation caused by save locking.
Enabled by metrics.scheduled_tick = true.
| Metric | Type | Unit | Collection | Attributes |
|---|---|---|---|---|
minecraft.server.world.scheduled_ticks.block |
LongGauge | {tick} |
Polled 1-min |
server.name, dimension.name
|
minecraft.server.world.scheduled_ticks.fluid |
LongGauge | {tick} |
Polled 1-min |
server.name, dimension.name
|
These metrics are only written when the queue is non-zero — silence is normal on an idle server. A consistently growing queue is an early-warning signal for server lag before TPS becomes measurably affected. Common causes include dense redstone contraptions and active water or lava flows.
| Metric name | Config flag |
|---|---|
minecraft.server.tps |
metrics.tps |
minecraft.server.tick_time |
metrics.tps |
minecraft.server.player.count |
metrics.player |
minecraft.server.player.latency |
metrics.player |
minecraft.server.jvm.memory.heap.used |
metrics.jvm |
minecraft.server.jvm.memory.heap.committed |
metrics.jvm |
minecraft.server.jvm.memory.heap.max |
metrics.jvm |
minecraft.server.jvm.gc.collections |
metrics.jvm |
minecraft.server.jvm.gc.pause_time |
metrics.jvm |
minecraft.server.jvm.cpu.load |
metrics.jvm |
minecraft.server.jvm.thread.count |
metrics.jvm |
minecraft.server.world.chunks.loaded |
metrics.world_chunk |
minecraft.server.world.chunks.force_loaded |
metrics.world_chunk |
minecraft.server.world.chunk.load |
metrics.world_chunk |
minecraft.server.world.chunk.unload |
metrics.world_chunk |
minecraft.server.world.chunk.generated |
metrics.chunk_generation |
minecraft.server.world.entity.living |
metrics.entity |
minecraft.server.world.entity.item |
metrics.item_entity |
minecraft.server.world.block_entity |
metrics.block_entity |
minecraft.server.world.save.duration |
metrics.world_save |
minecraft.server.world.scheduled_ticks.block |
metrics.scheduled_tick |
minecraft.server.world.scheduled_ticks.fluid |
metrics.scheduled_tick |