@babylonjs-toolkit/server 0.0.0-stage → 9.35.1

package/lib/admin/MaintenanceWindows.d.ts

@@ -0,0 +1,91 @@
+import type { AdminNoticePayload, MaintenanceWindowsRequest, MaintenanceWindowView } from "./AdminApiTypes.js";
+import type { MaintenanceWindowRecord } from "./AdminRecords.js";
+import type { AdminCoreServices } from "./AdminServices.js";
+import type { FleetDirectory } from "./FleetDirectory.js";
+import { type MaintenanceMode } from "./MaintenanceMode.js";
+import type { ServerEvents } from "./ServerEvents.js";
+/** Called when a window turns fleet maintenance on or off (the onMaintenanceChanged admin hook, R29). */
+export type WindowMaintenanceListener = (enabled: boolean, message: string | null, window: MaintenanceWindowRecord) => void;
+/** Fills a notice payload (FleetRoutes.createNoticePayload over the services). */
+export type NoticeFactory = (text: string, countdownSeconds: number | null) => AdminNoticePayload;
+/** The fleet's maintenance windows. */
+export declare class MaintenanceWindows {
+    /** The shared core services. */
+    private readonly services;
+    /** The fleet directory (notices and change announcements). */
+    private readonly fleet;
+    /** This instance's maintenance mode. */
+    private readonly maintenance;
+    /** The activity feed's server events. */
+    private readonly serverEvents;
+    /** Builds the warning notices. */
+    private readonly createNotice;
+    /** Listeners of maintenance turned on or off by a window. */
+    private readonly maintenanceListeners;
+    /**
+     * Creates the scheduler; nothing runs until the leader ticks.
+     * @param services The shared core services.
+     * @param fleet The fleet directory.
+     * @param maintenance This instance's maintenance mode.
+     * @param serverEvents The activity feed's server events.
+     * @param createNotice Builds a warning notice.
+     */
+    constructor(services: AdminCoreServices, fleet: FleetDirectory, maintenance: MaintenanceMode, serverEvents: ServerEvents, createNotice: NoticeFactory);
+    /**
+     * Calls back when a window turns maintenance on or off.
+     * @param listener The listener.
+     */
+    onMaintenanceChanged(listener: WindowMaintenanceListener): void;
+    /**
+     * Every window, soonest first.
+     * @returns The windows.
+     */
+    list(): Promise<MaintenanceWindowView[]>;
+    /**
+     * Schedules a window (POST maintenance/windows).
+     * @param request The window.
+     * @param createdBy Who schedules it.
+     * @returns The window.
+     * @throws AdminRequestError 400 for unreadable times, an end not after its start or in the past, or a negative warning.
+     */
+    create(request: MaintenanceWindowsRequest, createdBy: string): Promise<MaintenanceWindowView>;
+    /**
+     * Cancels a window; an active one turns fleet maintenance off first.
+     * @param windowId The window.
+     * @throws AdminRequestError 404 for an unknown window.
+     */
+    cancel(windowId: string): Promise<void>;
+    /** The leader tick: moves every open window on by the clock. */
+    tick(): Promise<void>;
+    /**
+     * Moves one window to the state the time calls for, doing what the step does.
+     * @param window The window.
+     * @param now The clock time.
+     * @returns The window's new state.
+     */
+    private advance;
+    /**
+     * Sends the fleet notice of an upcoming window (severity warning, with a countdown to its start).
+     * @param window The window.
+     * @param startsAt Its start, in milliseconds.
+     * @param now The clock time.
+     */
+    private sendWarning;
+    /**
+     * Turns fleet maintenance on with the window's message and allow lists.
+     * @param window The window.
+     */
+    private startMaintenance;
+    /**
+     * Turns fleet maintenance off at a window's end.
+     * @param window The window.
+     */
+    private endMaintenance;
+    /** Applies the stored fleet setting here at once and announces it to the other instances. */
+    private applyFleetSetting;
+    /**
+     * Every stored window.
+     * @returns The documents.
+     */
+    private storedWindows;
+}

package/lib/admin/MaintenanceWindows.js

@@ -0,0 +1,207 @@
+// Scheduled maintenance windows (game-server-admin-console T14 step 3, MaintenanceWindowView): a fleet leader tick
+// handler sends a warning notice warningMinutes before a window, turns fleet maintenance on with the window's message at
+// startsAt and off at endsAt. Without Redis the windows apply to this one instance.
+import { randomUUID } from "node:crypto";
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { MAINTENANCE_SETTINGS_ID } from "./MaintenanceMode.js";
+/** HTTP statuses of the refusals. */
+const HTTP_BAD_REQUEST = 400;
+const HTTP_NOT_FOUND = 404;
+/** Milliseconds per second and per minute. */
+const MILLISECONDS_PER_SECOND = 1000;
+const MILLISECONDS_PER_MINUTE = 60000;
+/** Window states the tick still acts on. */
+const OPEN_STATES = new Set(["scheduled", "warning", "active"]);
+/** The fleet's maintenance windows. */
+export class MaintenanceWindows {
+    /** The shared core services. */
+    services;
+    /** The fleet directory (notices and change announcements). */
+    fleet;
+    /** This instance's maintenance mode. */
+    maintenance;
+    /** The activity feed's server events. */
+    serverEvents;
+    /** Builds the warning notices. */
+    createNotice;
+    /** Listeners of maintenance turned on or off by a window. */
+    maintenanceListeners = [];
+    /**
+     * Creates the scheduler; nothing runs until the leader ticks.
+     * @param services The shared core services.
+     * @param fleet The fleet directory.
+     * @param maintenance This instance's maintenance mode.
+     * @param serverEvents The activity feed's server events.
+     * @param createNotice Builds a warning notice.
+     */
+    constructor(services, fleet, maintenance, serverEvents, createNotice) {
+        this.services = services;
+        this.fleet = fleet;
+        this.maintenance = maintenance;
+        this.serverEvents = serverEvents;
+        this.createNotice = createNotice;
+    }
+    /**
+     * Calls back when a window turns maintenance on or off.
+     * @param listener The listener.
+     */
+    onMaintenanceChanged(listener) {
+        this.maintenanceListeners.push(listener);
+    }
+    /**
+     * Every window, soonest first.
+     * @returns The windows.
+     */
+    async list() {
+        const records = (await this.storedWindows()).map((stored) => stored.value);
+        return records.sort((left, right) => left.startsAt.localeCompare(right.startsAt)).map(windowView);
+    }
+    /**
+     * Schedules a window (POST maintenance/windows).
+     * @param request The window.
+     * @param createdBy Who schedules it.
+     * @returns The window.
+     * @throws AdminRequestError 400 for unreadable times, an end not after its start or in the past, or a negative warning.
+     */
+    async create(request, createdBy) {
+        const startsAt = Date.parse(request.startsAt);
+        const endsAt = Date.parse(request.endsAt);
+        if (!Number.isFinite(startsAt) || !Number.isFinite(endsAt))
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "startsAt and endsAt must be ISO times");
+        if (endsAt <= startsAt)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "endsAt must be after startsAt");
+        if (endsAt <= this.services.clock.now())
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "endsAt must be in the future");
+        if (request.warningMinutes != null && request.warningMinutes < 0)
+            throw new AdminRequestError(HTTP_BAD_REQUEST, "warningMinutes may not be negative");
+        const record = {
+            windowId: randomUUID(),
+            startsAt: new Date(startsAt).toISOString(),
+            endsAt: new Date(endsAt).toISOString(),
+            message: request.message,
+            warningMinutes: request.warningMinutes,
+            allowUserIds: request.allowUserIds.slice(),
+            allowAddresses: request.allowAddresses.slice(),
+            leaveReadiness: request.leaveReadiness,
+            state: "scheduled",
+            createdBy: createdBy
+        };
+        await this.services.store.putDocument("maintenanceWindows", record.windowId, record, 0);
+        return windowView(record);
+    }
+    /**
+     * Cancels a window; an active one turns fleet maintenance off first.
+     * @param windowId The window.
+     * @throws AdminRequestError 404 for an unknown window.
+     */
+    async cancel(windowId) {
+        const stored = await this.services.store.getDocument("maintenanceWindows", windowId);
+        if (stored == null)
+            throw new AdminRequestError(HTTP_NOT_FOUND, "no such maintenance window");
+        if (stored.value.state === "active")
+            await this.endMaintenance(stored.value);
+        if (!OPEN_STATES.has(stored.value.state))
+            return;
+        await this.services.store.putDocument("maintenanceWindows", windowId, Object.assign({}, stored.value, { state: "cancelled" }), null);
+    }
+    /** The leader tick: moves every open window on by the clock. */
+    async tick() {
+        const now = this.services.clock.now();
+        for (const stored of await this.storedWindows()) {
+            if (!OPEN_STATES.has(stored.value.state))
+                continue;
+            const nextState = await this.advance(stored.value, now);
+            if (nextState === stored.value.state)
+                continue;
+            await this.services.store.putDocument("maintenanceWindows", stored.id, Object.assign({}, stored.value, { state: nextState }), stored.revision);
+        }
+    }
+    /**
+     * Moves one window to the state the time calls for, doing what the step does.
+     * @param window The window.
+     * @param now The clock time.
+     * @returns The window's new state.
+     */
+    async advance(window, now) {
+        const startsAt = Date.parse(window.startsAt);
+        const endsAt = Date.parse(window.endsAt);
+        if (now >= endsAt) {
+            if (window.state === "active")
+                await this.endMaintenance(window);
+            return "done";
+        }
+        if (now >= startsAt) {
+            if (window.state !== "active")
+                await this.startMaintenance(window);
+            return "active";
+        }
+        const warningAt = (window.warningMinutes != null) ? startsAt - window.warningMinutes * MILLISECONDS_PER_MINUTE : null;
+        if (window.state === "scheduled" && warningAt != null && now >= warningAt) {
+            await this.sendWarning(window, startsAt, now);
+            return "warning";
+        }
+        return window.state;
+    }
+    /**
+     * Sends the fleet notice of an upcoming window (severity warning, with a countdown to its start).
+     * @param window The window.
+     * @param startsAt Its start, in milliseconds.
+     * @param now The clock time.
+     */
+    async sendWarning(window, startsAt, now) {
+        const countdownSeconds = Math.ceil((startsAt - now) / MILLISECONDS_PER_SECOND);
+        const notice = this.createNotice(window.message, countdownSeconds);
+        await this.fleet.runOnAll("sendNotice", { roomId: null, playerId: 0, notice: notice });
+    }
+    /**
+     * Turns fleet maintenance on with the window's message and allow lists.
+     * @param window The window.
+     */
+    async startMaintenance(window) {
+        const settings = { enabled: true, message: window.message, allowUserIds: window.allowUserIds, allowAddresses: window.allowAddresses, leaveReadiness: window.leaveReadiness };
+        await this.services.store.putDocument("settings", MAINTENANCE_SETTINGS_ID, settings, null);
+        await this.applyFleetSetting();
+        this.serverEvents.record("maintenance on (scheduled window): " + window.message, null);
+        for (const listener of this.maintenanceListeners)
+            listener(true, window.message, window);
+    }
+    /**
+     * Turns fleet maintenance off at a window's end.
+     * @param window The window.
+     */
+    async endMaintenance(window) {
+        await this.services.store.deleteDocument("settings", MAINTENANCE_SETTINGS_ID);
+        await this.applyFleetSetting();
+        this.serverEvents.record("maintenance off (scheduled window ended)", null);
+        for (const listener of this.maintenanceListeners)
+            listener(false, null, window);
+    }
+    /** Applies the stored fleet setting here at once and announces it to the other instances. */
+    async applyFleetSetting() {
+        await this.maintenance.reloadFleetSetting(this.services.store);
+        await this.fleet.announceChange("settings");
+    }
+    /**
+     * Every stored window.
+     * @returns The documents.
+     */
+    storedWindows() {
+        return this.services.store.listDocuments("maintenanceWindows");
+    }
+}
+/**
+ * A window as the console sees it.
+ * @param record The stored window.
+ * @returns The view.
+ */
+function windowView(record) {
+    return {
+        windowId: record.windowId,
+        startsAt: record.startsAt,
+        endsAt: record.endsAt,
+        message: record.message,
+        warningMinutes: record.warningMinutes,
+        state: record.state,
+        createdBy: record.createdBy
+    };
+}

package/lib/admin/MetricsRoutes.d.ts

@@ -0,0 +1,8 @@
+import { type AdminApiRouter } from "./AdminApiRouter.js";
+import type { AdminServices } from "./AdminServices.js";
+/**
+ * Registers the metrics route.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export declare function registerMetricsRoutes(router: AdminApiRouter, services: AdminServices): void;

package/lib/admin/MetricsRoutes.js

@@ -0,0 +1,209 @@
+// The metrics route (game-server-admin-console DR §6.11 metrics row, D22, DR §8 rates): chart points for one instance or
+// the whole fleet over 15 min, 1 h, 6 h or 24 h, computed from the samples of MetricsSampler. With Redis every instance's
+// samples are read from its store stream; without Redis the fleet is this instance and its in-memory ring.
+import { AdminRequestError } from "./AdminApiRouter.js";
+import { RECORD_QUERY_MAX_LIMIT } from "./AdminStore.js";
+import { metricsStreamOf } from "./MetricsSampler.js";
+/** HTTP status of a successful read. */
+const HTTP_OK = 200;
+/** HTTP status of an invalid query. */
+const HTTP_BAD_REQUEST = 400;
+/** HTTP status of an unknown instance. */
+const HTTP_NOT_FOUND = 404;
+/** The processId query value of the whole fleet. */
+const FLEET_PROCESS_ID = "fleet";
+/** The range a query without one charts. */
+const DEFAULT_RANGE = "1h";
+/** Milliseconds per minute. */
+const MILLISECONDS_PER_MINUTE = 60000;
+/** How far back each range reaches, in milliseconds. */
+const RANGE_MILLISECONDS = {
+    "15m": 15 * MILLISECONDS_PER_MINUTE,
+    "1h": 60 * MILLISECONDS_PER_MINUTE,
+    "6h": 360 * MILLISECONDS_PER_MINUTE,
+    "24h": 1440 * MILLISECONDS_PER_MINUTE
+};
+/** Milliseconds per second. */
+const MILLISECONDS_PER_SECOND = 1000;
+/** Percent of one fully used CPU core. */
+const FULL_CORE_PERCENT = 100;
+/** Point fields the fleet series takes the largest instance value of; every other field is summed. */
+const FLEET_MAXIMUM_FIELDS = new Set(["eventLoopLagMilliseconds", "dedicatedFrameMillisecondsAverage"]);
+/**
+ * Registers the metrics route.
+ * @param router The admin API router.
+ * @param services The shared services.
+ */
+export function registerMetricsRoutes(router, services) {
+    const route = { method: "GET", pattern: "metrics", permission: "metrics.view", requiresStepUp: false, auditAction: null, handler: async (request) => ({ status: HTTP_OK, body: await buildMetricsSeries(services, request) }) };
+    router.register(route);
+}
+/**
+ * GET metrics: the chart points of one instance or of the fleet.
+ * @param services The shared services.
+ * @param request The request (query processId, range).
+ * @returns The series.
+ * @throws AdminRequestError 400 for an unknown range.
+ */
+async function buildMetricsSeries(services, request) {
+    const range = rangeOf(request.query.get("range"));
+    const processId = request.query.get("processId") ?? FLEET_PROCESS_ID;
+    const rangeMilliseconds = RANGE_MILLISECONDS[range];
+    const points = (processId === FLEET_PROCESS_ID)
+        ? sumFleetPoints(await readFleetSamples(services, rangeMilliseconds), services.metricsSampleIntervalMs)
+        : pointsFromSamples(await readInstanceSamples(services, processId, rangeMilliseconds));
+    return { processId: processId, range: range, points: points, grafanaUrl: services.config.admin.grafanaUrl };
+}
+/**
+ * The range of a query.
+ * @param text The range query value, or null.
+ * @returns The range (DEFAULT_RANGE when missing).
+ * @throws AdminRequestError 400 for an unknown value.
+ */
+function rangeOf(text) {
+    if (text == null || text === "")
+        return DEFAULT_RANGE;
+    if (!Object.hasOwn(RANGE_MILLISECONDS, text))
+        throw new AdminRequestError(HTTP_BAD_REQUEST, "range must be 15m, 1h, 6h or 24h");
+    return text;
+}
+/**
+ * One instance's samples: its store stream with Redis (which survives its restart), else this instance's ring.
+ * @param services The shared services.
+ * @param processId The instance.
+ * @param rangeMilliseconds How far back.
+ * @returns The samples, oldest first.
+ * @throws AdminRequestError 404 for another instance without Redis.
+ */
+async function readInstanceSamples(services, processId, rangeMilliseconds) {
+    if (services.store.kind === "redis")
+        return readStoredSamples(services, processId, rangeMilliseconds);
+    if (processId !== services.fleet.localProcessId)
+        throw new AdminRequestError(HTTP_NOT_FOUND, "no such instance");
+    return services.metricsSampler.samples(rangeMilliseconds);
+}
+/**
+ * The samples of every up instance (R33: without Redis the fleet is this instance).
+ * @param services The shared services.
+ * @param rangeMilliseconds How far back.
+ * @returns Each instance's samples, oldest first.
+ */
+async function readFleetSamples(services, rangeMilliseconds) {
+    if (services.store.kind !== "redis")
+        return [services.metricsSampler.samples(rangeMilliseconds)];
+    const instances = (await services.fleet.listInstances()).filter((instance) => instance.status === "up");
+    return Promise.all(instances.map((instance) => readStoredSamples(services, instance.processId, rangeMilliseconds)));
+}
+/**
+ * Reads an instance's stored samples of a recent period, newest pages first, until the period is covered.
+ * @param services The shared services.
+ * @param processId The instance.
+ * @param rangeMilliseconds How far back.
+ * @returns The samples, oldest first.
+ */
+async function readStoredSamples(services, processId, rangeMilliseconds) {
+    const cutoff = services.clock.now() - rangeMilliseconds;
+    const newestFirst = [];
+    let beforeSequence = undefined;
+    for (;;) {
+        const page = await services.store.readRecords(metricsStreamOf(processId), { beforeSequence: beforeSequence, limit: RECORD_QUERY_MAX_LIMIT, newestFirst: true });
+        const inRange = page.filter((record) => Date.parse(record.value.at) >= cutoff);
+        newestFirst.push(...inRange.map((record) => record.value));
+        if (page.length < RECORD_QUERY_MAX_LIMIT || inRange.length < page.length)
+            break;
+        beforeSequence = page[page.length - 1].sequence;
+    }
+    return newestFirst.reverse();
+}
+/**
+ * Chart points from one instance's consecutive samples (DR §8): the first sample only starts the rates.
+ * @param samples The samples, oldest first.
+ * @returns The points.
+ */
+function pointsFromSamples(samples) {
+    const points = [];
+    for (let i = 1; i < samples.length; i++) {
+        const point = pointBetween(samples[i - 1], samples[i]);
+        if (point != null)
+            points.push(point);
+    }
+    return points;
+}
+/**
+ * The chart point of a sample, with rates per second measured from the sample before it.
+ * @param previous The earlier sample.
+ * @param current The sample.
+ * @returns The point, or null when the samples share a time.
+ */
+function pointBetween(previous, current) {
+    const seconds = (Date.parse(current.at) - Date.parse(previous.at)) / MILLISECONDS_PER_SECOND;
+    if (!(seconds > 0))
+        return null;
+    // Samples stored before a counter existed lack it, so a missing total reads as 0.
+    const perSecond = (field) => counterRate(previous[field] ?? 0, current[field] ?? 0, seconds);
+    return {
+        at: current.at,
+        players: current.players,
+        sessions: current.sessions,
+        dedicatedSessions: current.dedicatedSessions,
+        joinsPerSecond: perSecond("joinsAccepted"),
+        refusalsPerSecond: perSecond("joinsRefused"),
+        authFailuresPerSecond: perSecond("authFailures"),
+        bytesInPerSecond: perSecond("bytesIn"),
+        bytesOutPerSecond: perSecond("bytesOut"),
+        messagesInPerSecond: perSecond("messagesIn"),
+        cpuPercent: perSecond("cpuSecondsTotal") * FULL_CORE_PERCENT,
+        residentMemoryBytes: current.residentMemoryBytes,
+        heapUsedBytes: current.heapUsedBytes,
+        eventLoopLagMilliseconds: current.eventLoopLagMilliseconds,
+        gcMillisecondsPerSecond: perSecond("gcSecondsTotal") * MILLISECONDS_PER_SECOND,
+        dedicatedFrameMillisecondsAverage: current.dedicatedFrameMillisecondsAverage,
+        dedicatedTickOverrunsPerSecond: perSecond("dedicatedTickOverruns"),
+        leaderboardAcceptedPerSecond: perSecond("leaderboardScoresAccepted"),
+        leaderboardRefusedPerSecond: perSecond("leaderboardScoresRefused")
+    };
+}
+/**
+ * The per-second rate of a counter between two samples (DR §8): a drop means the instance restarted, so it is 0.
+ * @param previous The earlier total.
+ * @param current The later total.
+ * @param seconds Seconds between the samples (more than 0).
+ * @returns The rate, never negative.
+ */
+function counterRate(previous, current, seconds) {
+    return (current >= previous) ? (current - previous) / seconds : 0;
+}
+/**
+ * The fleet series (DR §8): each instance's points aligned to the sample grid by flooring their time, then summed per
+ * grid step, except event-loop lag and dedicated frame time, where the worst instance is shown.
+ * @param samplesByInstance Each instance's samples, oldest first.
+ * @param gridMilliseconds The sample interval the times are floored to.
+ * @returns The fleet points, oldest first.
+ */
+function sumFleetPoints(samplesByInstance, gridMilliseconds) {
+    const buckets = new Map();
+    for (const samples of samplesByInstance) {
+        for (const point of pointsFromSamples(samples)) {
+            const bucketStart = Math.floor(Date.parse(point.at) / gridMilliseconds) * gridMilliseconds;
+            const existing = buckets.get(bucketStart);
+            if (existing == null)
+                buckets.set(bucketStart, Object.assign({}, point, { at: new Date(bucketStart).toISOString() }));
+            else
+                addPoint(existing, point);
+        }
+    }
+    return Array.from(buckets.entries()).sort((left, right) => left[0] - right[0]).map((entry) => entry[1]);
+}
+/**
+ * Adds another instance's point to a fleet point.
+ * @param total The fleet point (changed in place).
+ * @param point The instance's point of the same grid step.
+ */
+function addPoint(total, point) {
+    for (const field of Object.keys(point)) {
+        if (field === "at")
+            continue;
+        const figure = field;
+        total[figure] = FLEET_MAXIMUM_FIELDS.has(figure) ? Math.max(total[figure], point[figure]) : total[figure] + point[figure];
+    }
+}

package/lib/admin/MetricsSampler.d.ts

@@ -0,0 +1,124 @@
+import type { AdminCoreServices } from "./AdminServices.js";
+import type { AdminStream } from "./AdminStore.js";
+/** One sample of an instance's figures (D22). Counters are totals since start; rates are computed by the reader. */
+export interface MetricsSample {
+    /** ISO time of the sample. */
+    at: string;
+    /** Players connected to this instance's sessions. */
+    players: number;
+    /** Live sessions. */
+    sessions: number;
+    /** Live sessions a dedicated runner hosts. */
+    dedicatedSessions: number;
+    /** Accepted joins since start. */
+    joinsAccepted: number;
+    /** Refused joins since start. */
+    joinsRefused: number;
+    /** Refused joins since start, by ShutdownReason name. */
+    refusalsByReason: Record<string, number>;
+    /** Failed token checks since start. */
+    authFailures: number;
+    /** Frames from clients since start. */
+    framesIn: number;
+    /** Frames to clients since start. */
+    framesOut: number;
+    /** Frame bytes from clients since start. */
+    bytesIn: number;
+    /** Frame bytes to clients since start. */
+    bytesOut: number;
+    /** Frames (both directions) since start, by the client's transport. */
+    framesByTransport: Record<"websocket" | "webtransport", number>;
+    /** Room messages from clients since start. */
+    messagesIn: number;
+    /** Process CPU time since start, in seconds. */
+    cpuSecondsTotal: number;
+    /** Resident memory now, in bytes. */
+    residentMemoryBytes: number;
+    /** Used V8 heap now, in bytes. */
+    heapUsedBytes: number;
+    /** Mean event-loop delay since the previous sample, in milliseconds. */
+    eventLoopLagMilliseconds: number;
+    /** Time spent in garbage collection since start, in seconds. */
+    gcSecondsTotal: number;
+    /** Mean dedicated runner frame time since the previous sample, in milliseconds (0 without dedicated frames). */
+    dedicatedFrameMillisecondsAverage: number;
+    /** Dedicated frames longer than one tick since start. */
+    dedicatedTickOverruns: number;
+    /** Accepted leaderboard scores since start (game-server-leaderboards D21). */
+    leaderboardScoresAccepted: number;
+    /** Refused leaderboard scores since start (game-server-leaderboards D21). */
+    leaderboardScoresRefused: number;
+}
+/**
+ * The store stream of an instance's samples.
+ * @param processId The instance.
+ * @returns The stream name.
+ */
+export declare function metricsStreamOf(processId: string): AdminStream;
+/** Takes this instance's samples while the console runs. */
+export declare class MetricsSampler {
+    /** The shared core services. */
+    private readonly services;
+    /** The samples, oldest first. */
+    private readonly ring;
+    /** How many samples the ring and the store stream keep. */
+    private readonly capacity;
+    /** The sampler's own event-loop delay histogram, so Prometheus' windows are untouched (D22). */
+    private eventLoopMonitor;
+    /** The sample timer, while started. */
+    private sampleTimer;
+    /** True while a sample is being taken, so a slow store never stacks them. */
+    private isSampling;
+    /** The counters of the previous sample, for the dedicated frame mean between samples. */
+    private previousCounters;
+    /** Clock time of the last "metrics sample failed" warning. */
+    private lastSampleWarningAt;
+    /**
+     * Prepares an empty history; nothing is sampled until start().
+     * @param services The shared core services.
+     */
+    constructor(services: AdminCoreServices);
+    /** Starts sampling every metricsSampleIntervalMs. */
+    start(): void;
+    /** Stops sampling; the history taken so far stays readable. */
+    stop(): void;
+    /**
+     * This instance's samples of a recent period, from the in-memory ring.
+     * @param rangeMilliseconds How far back, in milliseconds.
+     * @returns The samples, oldest first.
+     */
+    samples(rangeMilliseconds: number): MetricsSample[];
+    /** Takes one sample into the ring and, with Redis, into the store stream; a failure is logged. */
+    private takeSample;
+    /**
+     * Appends a sample to this instance's store stream and trims it to the ring's capacity.
+     * @param sample The sample.
+     */
+    private storeSample;
+    /**
+     * This instance's figures now (DR §6.7).
+     * @returns The sample.
+     */
+    private buildSample;
+    /**
+     * The metrics counters, read fresh for this sample (R22), or zeros when metrics are off.
+     * @returns The counters.
+     */
+    private readCounters;
+    /**
+     * The mean dedicated frame time since the previous sample.
+     * @param counters The counters now.
+     * @returns The mean, in milliseconds (0 when no dedicated frame ran).
+     */
+    private dedicatedFrameAverage;
+    /**
+     * The mean event-loop delay since the previous sample; the histogram restarts afterwards.
+     * @returns The delay, in milliseconds (0 before any measurement).
+     */
+    private sampleEventLoopLag;
+    /**
+     * Logs a failed sample at warn, at most once per SAMPLE_WARNING_INTERVAL_MS.
+     * @param error What failed.
+     */
+    private warnSampleFailure;
+}