# 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_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 |