Time-series counters with optional tags. Show up on your plugin's dashboard via ctx.metrics.query.
ctx.metrics.record("commands_used") # +1
ctx.metrics.record("xp_awarded", value=25)
ctx.metrics.record("commands_used", tags={"command": "ban"})
# Read back (period / group_by / aggregate are keyword-only)
trend = ctx.metrics.query("commands_used", period="7d", group_by="command")
# {"labels": [...], "series": [{"name": "...", "data": [...]}], "total": float}
avg = ctx.metrics.query("xp_awarded", period="30d", aggregate="avg")
total = ctx.metrics.total("xp_awarded", period="30d")period accepts 1h, 24h, 7d, 30d, 90d (defaults: query 7d, total 30d). aggregate picks how points combine: sum (default), count, avg, max, min. Metric names: 1–64 chars, start with a letter or underscore, letters/digits/underscore only (no dots).
Limits: 50 distinct metric names and 1,000,000 stored data points per (server, plugin), 10 tag pairs per record (extras are silently dropped), tag keys up to 32 chars (letters/digits/underscore — malformed keys are silently dropped), tag values truncated to 128 chars, 90-day query window.
Unlike ctx.log, metrics calls are blocking RPCs that can raise (RateLimitError, RpcTimeoutError). If you record in the hot path of a command handler, wrap the call in try/except so a transient metrics failure can't break the user-visible work.