# Metriky pro Prometheus a Grafanu

> TPS, délka ticku, hráči, chunky po dimenzích, entity, paměť a náročnost jednotlivých modů jako endpoint, který čte Prometheus - za klíčem, který umí číst jen metriky, vypnuté, dokud ho nezapnete, a s dashboardem pro Grafanu přímo v jaru. Novinka 0.4.

Source: https://stygion.eu/cs/docs/keystone/metrics
Updated: 2026-11-16

## Proč

Obrazovka Performance v editoru ukáže, jak se serveru daří, když se na ni díváte. Monitoring to ukáže, i když ne: včerejší sekání, paměť, která týden stoupá před pádem, dimenze, která potichu zabrala půlku ticku. Tenhle modul dává čísla Keystone tam, kam se dívá Prometheus, Grafana, Victoria Metrics, Grafana Cloud a cokoli, co čte textový formát Prometheu.

## Zapnutí

Je **vypnuté**, dokud neřeknete, protože otevírá dveře v lokálním API.

1. V `openmetrics.toml` (nebo v **Settings**, `openmetrics.enabled`) nastavte `enabled = true` a restartujte server: `enabled` modulu se čte jednou, při startu serveru (editor to u něj označí a `/keystone reload` řekne, že čeká na restart).
2. Vyrobte klíč, který umí číst metriky a nic jiného (tajemství se ukáže jednou):
   `/keystone key new prometheus metrics.read`
3. Nasměrujte scrape job na lokální API (loopback, port 25586, pokud jste ho neměnili - scraper na jiném stroji potřebuje tunel nebo reverzní proxy, které věříte, nikdy port otevřený světu):

```yaml
scrape_configs:
  - job_name: keystone
    metrics_path: /v1/metrics/prometheus
    scrape_interval: 15s
    authorization:
      credentials: <klíč, který jste vyrobili>
    static_configs:
      - targets: ['127.0.0.1:25586']
```

`GET /v1/metrics/prometheus` odpovídá v textovém formátu Prometheu; s `?format=openmetrics` v OpenMetrics (rodiny čítačů bez `_total` a závěrečné `# EOF`). Volající bez klíče nebo s klíčem bez `metrics.read` je odmítnut jako u každé jiné cesty.

## Co zapisuje

| Metrika | Typ | Štítky | Co |
|---|---|---|---|
| `keystone_info` | gauge | `minecraft`, `loader` | vždy 1 |
| `keystone_tps` | gauge | | ticků za sekundu |
| `keystone_mspt` | gauge | `stat` = `median`, `p95`, `max` | milisekundy práce na tick za posledních sto ticků. Průměr schová sekání; tyhle ne |
| `keystone_last_tick_milliseconds` | gauge | | tick, který právě skončil |
| `keystone_players_online`, `keystone_players_max` | gauge | | online (bez neviditelných) a limit |
| `keystone_chunks_loaded` | gauge | `world` | načtené chunky po dimenzích (`labels.worlds` vypnuté: jeden součet, `world="all"`) |
| `keystone_dimension_tick_seconds_total` | counter | `world` | čas strávený tickováním každé dimenze; `rate(...)` je podíl času serveru, který svět bere |
| `keystone_entities`, `keystone_block_entities` | gauge | | v načteném světě (`census.enabled`) |
| `keystone_things_by_mod` | gauge | `mod` | entity a block entity, které má každý mod ve světě, největších `labels.mods-most` |
| `keystone_mod_milliseconds_per_tick` | gauge | `mod` | **jen když má [profiler](/docs/keystone/profiler) čerstvý běh** (`profile.fresh`, 30 minut): kolik z průměrného ticku mod zabral. Potom série zmizí, aby se stará čísla nevydávala za aktuální |
| `keystone_profile_age_seconds` | gauge | | před jak dlouhou dobou ten běh skončil |
| `keystone_player_ping_milliseconds` | gauge | `player` | **jen s `labels.players`**: viz níže |
| `keystone_jvm_memory_bytes` | gauge | `area`, `kind` | paměť heap a non-heap (`jvm`) |
| `keystone_jvm_gc_collections_total`, `keystone_jvm_gc_seconds_total` | counter | `collector` | garbage collection a čas v nich |
| `keystone_jvm_threads`, `keystone_uptime_seconds`, `keystone_process_cpu_ratio` | gauge | | vlákna, sekundy od startu JVM, podíl procesu na CPU |

Čísla se čtou **na serverovém vlákně, na časovači, a scrape čte hotový obraz**: scrapování každou sekundu serveru nestojí nic, co by neplatil už předtím. Sčítání entit projde načtený svět jednou za `census.every` sekund, ne jednou za scrape.

## Soukromí: jména zůstávají na serveru

**V metrikách není žádné jméno hráče**, dokud nenastavíte `labels.players = true` - pak se pod jménem každého online hráče ukáže jeho ping. Zapněte to jen tehdy, smí-li každý, kdo čte váš Prometheus, vidět, kdo je online. Hodnoty štítků se escapují, takže jméno nemůže přidat vlastní řádek. Jména modů v tom jsou (to je smysl); pozice, adresy, ID a chat nikdy.

## Nastavení

`openmetrics.toml`, nebo **Settings**.

| Nastavení | Výchozí | Co dělá |
|---|---|---|
| `enabled` | `false` | celý modul |
| `refresh` | `10` | sekundy mezi dvěma čteními hry |
| `census.enabled`, `census.every` | `true`, `30` | počítat entity a block entity a jak často (sekundy). Na velmi velkém světě vypněte |
| `labels.worlds` | `true` | série po dimenzích místo jednoho součtu |
| `labels.mods`, `labels.mods-most` | `true`, `50` | série po modech a kolik |
| `labels.players` | `false` | ping každého online hráče pod jeho jménem |
| `profile.fresh` | `30` | minuty, po které se ukazuje běh profileru |
| `jvm` | `true` | série o Javě |

## Dashboard pro Grafanu

Dashboard, který sedí přesně na tuhle verzi, je v jaru: **Metrics** v editoru má tlačítko ke stažení, nebo `GET /v1/metrics/dashboard` stejným klíčem. V Grafaně: Dashboards, New, Import, vyberte svůj Prometheus. Má dlaždice (TPS, p95 ticku, hráči, entity, block entity, heap), grafy TPS a délky ticku, chunky a podíl ticku po dimenzích, co má ve světě který mod, cenu modů z profileru a paměť Javy s garbage collection. Tvar, abyste si napsali vlastní panely:

```json
{ "title": "Milliseconds per tick (last 100 ticks)", "type": "timeseries",
  "targets": [ { "expr": "keystone_mspt{job=~\"$job\"}", "legendFormat": "{{stat}}" } ],
  "fieldConfig": { "defaults": { "unit": "ms", "min": 0 } } }
```

Pár dotazů, které se hodí:

| Otázka | Dotaz |
|---|---|
| Stíhá server? | `keystone_mspt{stat="p95"} > 45` |
| Který svět bere čas? | `rate(keystone_dimension_tick_seconds_total[5m])` |
| Teče paměť? | `keystone_jvm_memory_bytes{area="heap",kind="used"}` za týden |
| Čas ztracený garbage collection | `rate(keystone_jvm_gc_seconds_total[1m])` |
| Alert: TPS pod 15 po 5 minut | `avg_over_time(keystone_tps[5m]) < 15` |

## API

| Cesta | Scope | |
|---|---|---|
| `GET /v1/metrics/prometheus` | `metrics.read` | metriky (`?format=openmetrics`) |
| `GET /v1/metrics/dashboard` | `metrics.read` | dashboard pro Grafanu jako JSON |

`metrics.read` otevírá tyhle dvě cesty a nic jiného, takže klíč v konfiguraci Prometheu umí číst čísla a nic nezmění.
