prometheus-spigot/README.md

Prometheus Spigot

Prometheus Spigot exposes server metrics at a configurable HTTP endpoint for Prometheus scrapes. It targets Spigot/Paper 1.21.11 and uses the JDK HTTP server with bearer token auth.

Install

1. Build the plugin: ./gradlew build
2. Copy the JAR from build/libs/ into your server plugins/ directory.
3. Start the server once to generate plugins/PrometheusSpigot/config.yml and token.

Build with Docker

If you do not have Gradle installed, you can build using Docker:

docker build -t prometheus-spigot-build .

Then extract the jar from the image:

docker create --name prometheus-spigot-build prometheus-spigot-build
docker cp prometheus-spigot-build:/workspace/build/libs ./build/libs
docker rm prometheus-spigot-build

Build with Make

If you prefer Make targets:

make build

Docker build + extract:

make docker-jar

Configure

config.yml (defaults shown):

http:
  bind_address: "0.0.0.0"
  port: 9149
  path: "/metrics"
  bearer_token: ""
metrics:
  enable_jvm: true
  enable_process: true
  entity_snapshot_interval_seconds: 15
movement:
  count_block_changes_only: true

Scrape Example

scrape_configs:
  - job_name: spigot
    metrics_path: /metrics
    static_configs:
      - targets: ["server:9149"]
    authorization:
      credentials: "<bearer_token>"

CI Release Notes

The Gitea workflow expects these secrets/variables:

• GITEA_TOKEN: built-in Actions token with repo write access for tags/releases.
• GITEA_API_URL: API base URL, for example https://git.garvis.dev/api/v1.
• Optional fallback: GITEA_SERVER_URL or the runner GITHUB_SERVER_URL are used if the API URL is not set.

Metrics

Some metrics depend on server implementations (TPS/MSPT, player ping, tile entities). If a method is unavailable on your server build, those metrics are omitted. Entity and tile counts are updated on a periodic main-thread snapshot.

Metric	Type	Labels	Description
spigot_chat_messages_total	counter	none	Total chat messages sent
spigot_player_movements_total	counter	none	Total player movement events
spigot_players_joined_total	counter	none	Total player joins
spigot_players_quit_total	counter	none	Total player quits
spigot_chunk_loads_total	counter	none	Total chunk load events
spigot_chunk_unloads_total	counter	none	Total chunk unload events
spigot_chunks_generated_total	counter	none	Total generated chunks
spigot_plugin_enable_total	counter	none	Total plugin enable events
spigot_plugin_disable_total	counter	none	Total plugin disable events
spigot_blocks_broken_total	counter	material	Blocks broken by material
spigot_player_deaths_total	counter	cause	Player deaths by cause
spigot_player_logins_failed_total	counter	reason	Failed player logins by reason
spigot_commands_blocked_total	counter	command	Blocked commands by name
spigot_commands_executed_total	counter	command,source	Commands executed by source
spigot_players_online	gauge	none	Online player count
spigot_players_max	gauge	none	Max player slots
spigot_worlds_loaded	gauge	none	Loaded world count
spigot_chunks_loaded	gauge	none	Loaded chunk count
spigot_plugins_loaded	gauge	none	Loaded plugin count
spigot_tasks_pending	gauge	none	Pending scheduled tasks
spigot_tasks_running	gauge	none	Active scheduled tasks
spigot_entities_total	gauge	type	Entities by type
spigot_tile_entities_total	gauge	type	Tile entities by type
spigot_player_ping_ms_player	gauge	player	Player ping in milliseconds
spigot_tps	gauge	interval	Server TPS by interval (1m/5m/15m)
spigot_mspt	gauge	none	Average milliseconds per tick
process_uptime_seconds	gauge	none	Process uptime in seconds
jvm_threads	gauge	none	Current JVM thread count
jvm_memory_used_bytes	gauge	area	JVM memory used in bytes
jvm_memory_max_bytes	gauge	area	JVM memory max in bytes
jvm_thread_cpu_seconds_total	counter	none	Total CPU seconds used by JVM threads
jvm_gc_pause_seconds_count	counter	gc	GC pause count
jvm_gc_pause_seconds_total	counter	gc	Total GC pause time
spigot_player_ping_ms_bucket	histogram	le	Player ping histogram buckets
spigot_player_ping_ms_sum	histogram	none	Player ping histogram sum
spigot_player_ping_ms_count	histogram	none	Player ping histogram count