Repository navigation
Metrics
Every metric starts with minecraft_. Names never change within a major version: dashboards and alerts depend on them.
How to read the tables:
-
Labels lists the labels a metric carries. Every metric also gets
instanceandjobfrom Prometheus. - A
playerlabel appears only withEXPORTER_PLAYERS=true, the default. Withfalse, player statistics add every player up into one series, and the online players' details, positions, chat counts, first joins, and last seen go away. - A permission in a section's title means the metrics need a token with it. Without it, they stay absent.
- Counters marked “since start” count from the exporter's start. The rest come from the server as it is now, or from the game's lifetime statistics.
From GET /server, on every scrape.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_up |
gauge | 1 when WorldAPI answered the last scrape, 0 when it didn't | |
minecraft_info |
gauge |
brand, minecraft_version, build, api_version, worldapi_version, platform, side
|
Always 1: the server's software and versions, and where WorldAPI runs. platform is paper, fabric, or neoforge, side is dedicated, or integrated for a singleplayer world. WorldAPI before 4.2.0 reads as paper and dedicated
|
minecraft_start_time_seconds |
gauge | When the server started, in Unix seconds | |
minecraft_players_online |
gauge | Players online now | |
minecraft_players_max |
gauge | The player limit | |
minecraft_tick_rate |
gauge | Ticks per second the server aims for | |
minecraft_tick_frozen |
gauge | 1 while the game's ticks are frozen | |
minecraft_paused |
gauge | 1 while a singleplayer game is paused, so nothing ticks | |
minecraft_whitelist_enabled |
gauge | 1 when only whitelisted players may join | |
minecraft_datapacks_enabled |
gauge | Datapacks enabled, built-in ones included | |
minecraft_players_known |
gauge | Players who have ever joined (from GET /players, on the statistics cadence) |
From GET /server/performance, on every scrape.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_tps |
gauge |
window: 1m, 5m, 15m
|
Ticks per second, averaged over the window |
minecraft_tick_duration_seconds |
gauge |
quantile: 0.5, 0.95, 0.99, 1
|
How long a tick takes over recent ticks. 1 is the slowest |
minecraft_tick_duration_average_seconds |
gauge | The average tick over recent ticks | |
minecraft_cpu_usage_ratio |
gauge |
scope: process, system
|
CPU in use, from 0 to 1 across every core |
minecraft_cpu_cores |
gauge | CPU cores the server sees |
From GET /server/performance, on every scrape.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_jvm_memory_used_bytes |
gauge |
area: heap, nonheap
|
JVM memory in use |
minecraft_jvm_memory_committed_bytes |
gauge | area |
Memory the system has given the JVM |
minecraft_jvm_memory_max_bytes |
gauge | area |
The most memory the JVM may use, when it has a limit |
minecraft_jvm_memory_pool_used_bytes |
gauge |
pool, area
|
Memory a pool uses |
minecraft_jvm_memory_pool_committed_bytes |
gauge |
pool, area
|
Memory the JVM holds for a pool |
minecraft_jvm_memory_pool_max_bytes |
gauge |
pool, area
|
The most memory a pool may use, when it has a limit |
minecraft_jvm_gc_collections_total |
counter | gc |
Garbage collections by collector |
minecraft_jvm_gc_seconds_total |
counter | gc |
Time spent collecting garbage, by collector |
minecraft_jvm_threads |
gauge |
state: live, daemon, peak
|
Threads live now, daemons among them, and the peak since start |
minecraft_jvm_classes_loaded |
gauge | Classes loaded now | |
minecraft_jvm_buffer_pool_used_bytes |
gauge | pool |
Memory a buffer pool uses |
minecraft_jvm_buffer_pool_capacity_bytes |
gauge | pool |
Capacity of a buffer pool's buffers |
minecraft_jvm_buffer_pool_buffers |
gauge | pool |
Buffers in a pool |
From GET /worlds and GET /server/performance, on every scrape.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_world_info |
gauge |
world, environment: normal, nether, the_end
|
Always 1: a world and its environment |
minecraft_world_chunks_loaded |
gauge | world |
Chunks loaded |
minecraft_world_entities |
gauge | world |
Entities in loaded chunks |
minecraft_world_entities_by_type |
gauge |
world, type
|
Entities of the world's most common types, as WorldAPI names them |
minecraft_world_block_entities |
gauge | world |
Block entities, like chests and hoppers, in loaded chunks |
minecraft_world_players |
gauge | world |
Players in the world |
minecraft_world_days |
gauge | world |
Days the world has lived. /time set can move it back. Called minecraft_world_days_total, a counter, before 3.0.0 |
minecraft_world_time_ticks |
gauge | world |
Time of day, from 0 at sunrise to 23999 |
minecraft_world_raining |
gauge | world |
1 while it rains or snows |
minecraft_world_thundering |
gauge | world |
1 during a thunderstorm |
minecraft_world_border_size_blocks |
gauge | world |
The world border's side |
From GET /players/online, on every scrape. Only with EXPORTER_PLAYERS=true.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_player_info |
gauge |
player, uuid, world, gamemode
|
Always 1: a player online now, their world and game mode |
minecraft_player_ping_seconds |
gauge | player |
Ping |
minecraft_player_health |
gauge | player |
Health, 20 when full |
minecraft_player_food |
gauge | player |
The hunger bar, 20 when full |
minecraft_player_level |
gauge | player |
Experience level |
minecraft_player_idle_seconds |
gauge | player |
How long the player hasn't moved or acted |
From GET /leaderboards/<statistic> and GET /players, refreshed every EXPORTER_STATS_INTERVAL, a batch per scrape. These are the game's lifetime statistics for everyone who has played, not only who's online. Each carries player, or none when players add up.
| Metric | Type | Leaderboard | What it shows |
|---|---|---|---|
minecraft_player_play_time_seconds_total |
counter | custom:play_time |
Time played |
minecraft_player_deaths_total |
counter | custom:deaths |
Deaths |
minecraft_player_mob_kills_total |
counter | custom:mob_kills |
Mobs killed |
minecraft_player_player_kills_total |
counter | custom:player_kills |
Players killed |
minecraft_player_damage_dealt_total |
counter | custom:damage_dealt |
Damage dealt, in health points (2 per heart) |
minecraft_player_damage_taken_total |
counter | custom:damage_taken |
Damage taken, in health points |
minecraft_player_blocks_mined_total |
counter | mined:* |
Blocks mined |
minecraft_player_items_crafted_total |
counter | crafted:* |
Items crafted |
minecraft_player_distance_meters_total |
counter | travel |
Distance traveled in every way |
minecraft_player_jumps_total |
counter | custom:jump |
Jumps |
minecraft_player_fish_caught_total |
counter | custom:fish_caught |
Fish caught |
minecraft_player_animals_bred_total |
counter | custom:animals_bred |
Animals bred |
minecraft_player_animals_tamed_total |
counter | tamed |
Animals tamed, as WorldAPI counts them |
minecraft_player_villager_trades_total |
counter | custom:traded_with_villager |
Trades with villagers |
minecraft_player_items_enchanted_total |
counter | custom:enchant_item |
Items enchanted |
minecraft_player_diamonds_mined_total |
counter | diamonds |
Diamond ores mined |
minecraft_player_ancient_debris_mined_total |
counter | netherite |
Ancient debris mined |
minecraft_player_experience_gained_total |
counter | experience |
Experience points gained, as WorldAPI counts them |
minecraft_player_advancements |
gauge | advancements |
Advancements finished, recipes left out |
minecraft_player_first_join_timestamp_seconds |
gauge | (GET /players) |
When the player first joined, in Unix seconds. Only per player |
minecraft_player_last_seen_timestamp_seconds |
gauge | (GET /players) |
When the player was last online, in Unix seconds. Only per player |
From GET /events, on every scrape. Counters since start: the first scrape only marks where to begin.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_events_total |
counter | type |
Events WorldAPI recorded, by type: player.join, player.leave, player.kick, player.death, player.advancement, player.chat, and the recorded topics of plugins that share data through WorldAPI, like boss kills |
minecraft_deaths_total |
counter |
cause, killer
|
Player deaths by cause and the killer's entity type. killer is empty when nothing killed the player |
minecraft_advancements_total |
counter |
frame: task, goal, challenge
|
Advancements players made |
minecraft_first_joins_total |
counter | Players who joined for the first time |
From GET /events. WorldAPI records chat only with events.chat: true in its config. Counter since start.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_player_chat_messages_total |
counter | player |
Chat messages a player sent. Only per player |
Chat also shows as type="player.chat" in minecraft_events_total.
From GET /players/online, on every scrape. Only per player.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_player_position_blocks |
gauge |
player, world, axis: x, y, z
|
Where a player stands |
From GET /worlds/<world>/entities/summary, on the statistics cadence.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_world_dropped_items |
gauge | world |
Item stacks lying on the ground in loaded chunks |
minecraft_world_dropped_item_count |
gauge | world |
Items lying on the ground, stacks added up |
minecraft_world_villagers |
gauge | world |
Villagers in loaded chunks |
minecraft_world_named_mobs |
gauge | world |
Mobs with a name tag |
minecraft_world_tamed_mobs |
gauge | world |
Tamed animals |
minecraft_chunk_entities |
gauge |
world, chunk
|
Entities in the world's five busiest chunks. chunk is x,z in chunk coordinates |
minecraft_chunk_block_entities |
gauge |
world, chunk
|
Block entities in those chunks |
minecraft_chunk_hoppers |
gauge |
world, chunk
|
Hoppers in those chunks |
From GET /server/plugins, on the statistics cadence.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_plugin_enabled |
gauge |
plugin, version, kind
|
A plugin or mod on the server: 1 while enabled. kind is plugin on Paper, mod on Fabric and NeoForge |
From GET /server/system, on every scrape. A metric stays absent when the host doesn't report it, like container limits outside a container.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_host_load_average |
gauge |
window: 1m, 5m, 15m
|
The host's load average |
minecraft_host_cpus |
gauge | CPUs the host has | |
minecraft_host_memory_total_bytes |
gauge | The host's memory | |
minecraft_host_memory_available_bytes |
gauge | Memory the host can still give out | |
minecraft_host_swap_total_bytes |
gauge | The host's swap | |
minecraft_host_swap_free_bytes |
gauge | Swap not in use | |
minecraft_disk_total_bytes |
gauge | The disk under the server folder | |
minecraft_disk_free_bytes |
gauge | Space the server may still use on that disk | |
minecraft_container_memory_limit_bytes |
gauge | The container's memory limit | |
minecraft_container_memory_used_bytes |
gauge | Memory the container uses | |
minecraft_container_cpu_limit |
gauge | CPUs the container may use | |
minecraft_process_open_files |
gauge | Files the server has open | |
minecraft_process_max_open_files |
gauge | The most files the server may open | |
minecraft_process_resident_memory_bytes |
gauge | Memory the server's process holds, the JVM's own included | |
minecraft_java_info |
gauge |
name, vendor, version
|
Always 1: the Java runtime the server runs on |
From GET /server/logs, the newest 1000 lines on every scrape. Counters since start.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_log_messages_total |
counter | level |
Console lines by level: info, warn, error, and others as they come |
minecraft_log_problems_total |
counter |
level, logger
|
Warnings, errors, and fatal lines by who logged them |
From GET /server/bans, /server/ops, and /server/whitelist, on the statistics cadence. This permission also bans and kicks: leave it out unless you need these counts.
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_bans |
gauge |
kind: player, ip
|
Bans in force |
minecraft_operators |
gauge | Operators | |
minecraft_whitelist_players |
gauge | Players on the whitelist |
| Metric | Type | Labels | What it shows |
|---|---|---|---|
minecraft_exporter_scrape_duration_seconds |
gauge | How long reading WorldAPI took | |
minecraft_exporter_endpoint_allowed |
gauge | endpoint |
1 when WorldAPI lets the exporter read an endpoint, 0 when the token lacks its permission |
minecraft_exporter_request_errors_total |
counter |
target, endpoint
|
WorldAPI requests that failed. A refusal (401, 403) doesn't count. Only on /metrics
|
minecraft_exporter_build_info |
gauge |
version, goversion
|
Always 1: the exporter's version. Only on /metrics
|
/metrics also carries the standard go_* and process_* metrics of the exporter itself. target is default for the server at WORLDAPI_URL, or the name from the targets file.
For server owners
For developers