128 lines
5.2 KiB
Markdown
128 lines
5.2 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
docker build -t prometheus-spigot-build .
|
|
```
|
|
|
|
Then extract the jar from the image:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
make build
|
|
```
|
|
|
|
Docker build + extract:
|
|
|
|
```bash
|
|
make docker-jar
|
|
```
|
|
|
|
## Configure
|
|
|
|
`config.yml` (defaults shown):
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
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_player_movements_by_player_total | counter | player | Player movements by player |
|
|
| 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_blocks_broken_by_player_total | counter | player,material | Blocks broken by player and material |
|
|
| spigot_blocks_placed_total | counter | material | Blocks placed by material |
|
|
| spigot_blocks_placed_by_player_total | counter | player,material | Blocks placed by player and material |
|
|
| spigot_items_crafted_total | counter | material | Items crafted by material |
|
|
| spigot_items_crafted_by_player_total | counter | player,material | Items crafted by player and material |
|
|
| spigot_entities_killed_total | counter | entity,killer | Entities killed by player |
|
|
| 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 |
|