Custom telemetry

Import com.serverspulse.agent.api.ServersPulse from the platform agent jar. The package remains unrelocated in com.serverspulse:serverspulse-minestom:1.0.0.

ServersPulse.gauge("match.queue_size", 12.0);
ServersPulse.counter("match.completed", 1.0);
ServersPulse.event("match.finished", java.util.Map.of("mode", "duel"));
ServersPulse.annotate("Deployed game rules revision 12");

All four static methods return boolean; false means disabled or rejected. Before startup and after shutdown calls have no effect. Gauges keep the last interval value; counters sum nonnegative deltas. Values must be finite. Names and field keys match [a-zA-Z][a-zA-Z0-9_.-]{0,63}. There are no labels. The agent permits 64 distinct metric name/kind pairs per runtime, 100 queued events, and 10,000 accepted calls per minute. Events contain at most 16 scalar fields (null, boolean, number, string), each string at most 256 UTF-8 bytes. Annotations use event type annotation and the text field.

Free servers accept at most 16 distinct metric name/kind pairs and 20 events per snapshot. Other plans accept 64 and 100. The backend name registry lasts for the server's lifetime; use stable names, never player IDs or dynamically generated names. Exceeding limits rejects the snapshot with 422. Plan submission intervals also apply (429 with Retry-After). Do not send sensitive data in custom fields.

Custom telemetry rides POST /api/v1/ingest with the same X-API-Key authentication and snapshot retries. The optional customTelemetry object has batchId (UUID), metrics (name, kind, value), and events (timestamp, type, fields). The server ID always comes from authentication. Batch IDs deduplicate retries. Event and metric times must be within the past day and at most five minutes ahead. Buffers are in-memory and can lose data after exhausted retries or shutdown.

The authenticated read route is GET /api/v1/servers/{serverID}/custom-telemetry?from=RFC3339&to=RFC3339. It requires JWT authentication and the overview-metrics sharing permission. Ranges are restricted to the owner's plan retention and at most 90 days. The response contains points (time, name, kind, value) and events (timestamp, type, fields). Gauges average and counter deltas sum in five-minute buckets. Responses cap points at 10,000 and events at the latest 500; narrow the range when needed. The server overview has a series selector, chart markers and event list. Stored series use TimescaleDB; data has a 90-day physical ceiling and is pruned on plan downgrades alongside normal metrics. Read windows enforce plan retention even before physical cleanup.