Skip to content

Metrics

Pavel Erokhin edited this page Nov 9, 2026 · 5 revisions

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 instance and job from Prometheus.
  • A player label appears only with EXPORTER_PLAYERS=true, the default. With false, 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.

Server

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)

Performance

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

JVM

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

Worlds

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

Online players

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

Player statistics

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

Activity

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

Chat (chat:read)

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.

Positions (players:private)

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

Crowded worlds (server:read)

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

Plugins (server:read)

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

Host (system:read)

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

Console (logs:read)

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

Moderation (players:moderate)

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

The exporter

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.

Clone this wiki locally