@marinoscar/platform-contract 0.0.0-stage → 0.1.0-next.4

package/dist/cjs/telemetry/dashboard.js

@@ -0,0 +1,755 @@
+"use strict";
+// =============================================================================
+// Telemetry dashboard (issue #577; moved here from the API's
+// `telemetry/dto/telemetry-dashboard.dto.ts` by #702)
+// =============================================================================
+//
+//   GET /api/admin/telemetry/dashboard/summary       → telemetryDashboardSummarySchema
+//   GET /api/admin/telemetry/dashboard/timeseries    → telemetryDashboardTimeseriesSchema
+//   GET /api/admin/telemetry/dashboard/top           → telemetryDashboardTopSchema
+//   GET /api/admin/telemetry/dashboard/events        → telemetryDashboardEventsSchema
+//   GET /api/admin/telemetry/dashboard/filters       → telemetryDashboardFiltersSchema
+//   GET /api/admin/telemetry/dashboard/metrics       → telemetryDashboardMetricsSchema (#601)
+//   GET /api/admin/telemetry/dashboard/metric-groups → telemetryDashboardMetricGroupsSchema (#680)
+//
+// Common query: `range` (15m|1h|6h|24h|7d, default 1h) OR `from`+`to` (ISO,
+// from < to, to <= now + 1 min, span <= 30 days); `service`, `instance`
+// (checked by the service against the values seen in the range);
+// `buckets` (30|60, default 60). Every query value arrives as a string.
+//
+// METRIC GROUP IDS ARE AN OPEN SET (#680): the platform registers six and an
+// app may register more, so the contract types `group` as an id (a string
+// matching `METRIC_GROUP_ID_PATTERN`). A server that knows its registered set
+// builds its own `/metrics` schemas with `createTelemetryDashboardMetricsQuerySchema`
+// and `createTelemetryDashboardMetricsSchema`, passing the group schema it
+// documents and checks (the API passes one read from its live registry).
+//
+// ⚠ OpenAPI is generated from these schemas. Field order, `.describe()` texts
+// and enum order are part of the published document.
+// =============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.telemetryDashboardPanelDataSchema = exports.telemetryDashboardPanelsSchema = exports.telemetryDashboardPanelSchema = exports.telemetryDashboardMetricGroupsSchema = exports.telemetryDashboardMetricGroupSchema = exports.telemetryDashboardMetricsSchema = exports.metricTableSchema = exports.metricCellSchema = exports.metricColumnSchema = exports.metricSeriesSchema = exports.metricPointSchema = exports.telemetryDashboardFiltersSchema = exports.telemetryDashboardEventsSchema = exports.dashboardEventSchema = exports.telemetryDashboardTopSchema = exports.topErrorSchema = exports.topRouteSchema = exports.telemetryDashboardTimeseriesSchema = exports.logsBucketSchema = exports.apiBucketSchema = exports.telemetryDashboardSummarySchema = exports.telemetryDashboardUnknownRoutesSchema = exports.unknownRouteSchema = exports.telemetryDashboardTileSchema = exports.telemetryDashboardEnvelopeSchema = exports.telemetryDashboardMetricsQuerySchema = exports.metricGroupIdSchema = exports.telemetryDashboardEventsQuerySchema = exports.telemetryDashboardTopQuerySchema = exports.telemetryDashboardTimeseriesQuerySchema = exports.telemetryDashboardQuerySchema = void 0;
+exports.refineWindow = refineWindow;
+exports.metricGroupQuerySchema = metricGroupQuerySchema;
+exports.createTelemetryDashboardMetricsQuerySchema = createTelemetryDashboardMetricsQuerySchema;
+exports.createTelemetryDashboardMetricsSchema = createTelemetryDashboardMetricsSchema;
+const zod_1 = require("zod");
+const constants_js_1 = require("./constants.js");
+const enum_js_1 = require("./enum.js");
+const presentation_js_1 = require("./presentation.js");
+// ---- queries -----------------------------------------------------------------
+const commonShape = {
+    /** Relative window ending now. Default `1h`. Not with `from`/`to`. */
+    range: (0, enum_js_1.wireEnum)(constants_js_1.DASHBOARD_RANGES).optional().describe('Relative window ending now. Default `1h`. Not with `from`/`to`.'),
+    /** Absolute window start (ISO 8601). Requires `to`. */
+    from: zod_1.z.iso.datetime({ offset: true }).optional().describe('Absolute window start (ISO 8601). Requires `to`.'),
+    /** Absolute window end (ISO 8601), at most 1 minute in the future. Requires `from`; span at most 30 days. */
+    to: zod_1.z.iso
+        .datetime({ offset: true })
+        .optional()
+        .describe('Absolute window end (ISO 8601), at most 1 minute in the future. Requires `from`; span <= 30 days.'),
+    /** Only this service. Must be one of `/filters` `services` for the range. */
+    service: zod_1.z
+        .string()
+        .min(1)
+        .max(constants_js_1.DASHBOARD_FILTER_VALUE_MAX)
+        .optional()
+        .describe('Only this service. Must be one of `/filters` `services` for the range.'),
+    /** Only this instance (`app.instance.id`). Must be one of `/filters` `instances` for the range. */
+    instance: zod_1.z
+        .string()
+        .min(1)
+        .max(constants_js_1.DASHBOARD_FILTER_VALUE_MAX)
+        .optional()
+        .describe('Only this instance (`app.instance.id`). Must be one of `/filters` `instances` for the range.'),
+    /** Target number of buckets: `30` or `60` (default). */
+    buckets: (0, enum_js_1.wireEnum)(constants_js_1.DASHBOARD_BUCKET_COUNTS).optional().describe('Target number of buckets: `30` or `60` (default).'),
+};
+/**
+ * The cross-field rules of a dashboard window, as a `superRefine`: `range`
+ * or `from`+`to` (never both, never one of the pair), `from < to`, `to` at
+ * most 1 minute in the future and a span of at most 30 days. Every dashboard
+ * query schema applies it; an app's own dashboard query applies it too.
+ *
+ * @stability stable
+ */
+function refineWindow(value, ctx) {
+    const hasFrom = value.from !== undefined;
+    const hasTo = value.to !== undefined;
+    if (value.range !== undefined && (hasFrom || hasTo)) {
+        ctx.addIssue({ code: 'custom', path: ['range'], message: 'Use either `range` or `from`/`to`, not both.' });
+        return;
+    }
+    if (hasFrom !== hasTo) {
+        ctx.addIssue({ code: 'custom', path: [hasFrom ? 'to' : 'from'], message: '`from` and `to` go together.' });
+        return;
+    }
+    if (!hasFrom)
+        return;
+    const from = Date.parse(value.from);
+    const to = Date.parse(value.to);
+    if (!(from < to)) {
+        ctx.addIssue({ code: 'custom', path: ['from'], message: '`from` must be before `to`.' });
+        return;
+    }
+    if (to > Date.now() + constants_js_1.DASHBOARD_FUTURE_SKEW_MS) {
+        ctx.addIssue({ code: 'custom', path: ['to'], message: '`to` may be at most 1 minute in the future.' });
+    }
+    if (to - from > constants_js_1.DASHBOARD_MAX_SPAN_MS) {
+        ctx.addIssue({ code: 'custom', path: ['from'], message: 'The window may span at most 30 days.' });
+    }
+}
+/**
+ * The query every dashboard route shares: `range` or `from`+`to`, `service`,
+ * `instance` and `buckets`, with {@link refineWindow}.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardQuerySchema = zod_1.z.object(commonShape).superRefine(refineWindow);
+/**
+ * `GET …/dashboard/timeseries` query: the common query plus `panel`
+ * (`api` or `logs`).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardTimeseriesQuerySchema = zod_1.z
+    .object({
+    ...commonShape,
+    /** `api` (status classes, p95) or `logs` (severity bands). */
+    panel: (0, enum_js_1.wireEnum)(constants_js_1.DASHBOARD_PANELS).describe('`api` (status classes, p95) or `logs` (severity bands).'),
+})
+    .superRefine(refineWindow);
+/**
+ * `GET …/dashboard/top` query: the common query plus `kind` (`routes` or
+ * `errors`).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardTopQuerySchema = zod_1.z
+    .object({
+    ...commonShape,
+    /** `routes` (by 5xx, then 4xx except 401, then p95) or `errors` (log messages). */
+    kind: (0, enum_js_1.wireEnum)(constants_js_1.DASHBOARD_TOP_KINDS).describe('`routes` (by 5xx, then 4xx except 401, then p95) or `errors` (log messages).'),
+})
+    .superRefine(refineWindow);
+const SEVERITY_LIST = new RegExp(`^(${constants_js_1.DASHBOARD_EVENT_SEVERITIES.join('|')})(,(${constants_js_1.DASHBOARD_EVENT_SEVERITIES.join('|')}))*$`);
+/**
+ * `GET …/dashboard/events` query: the common query plus `severity` (a comma
+ * list of {@link DASHBOARD_EVENT_SEVERITIES}), `q` (a log body substring) and
+ * `cursor`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardEventsQuerySchema = zod_1.z
+    .object({
+    ...commonShape,
+    /** Comma-separated severities: `error`, `warn`, `info`. Default `error,warn`. */
+    severity: zod_1.z
+        .string()
+        .regex(SEVERITY_LIST, 'A comma-separated list of error, warn, info.')
+        .optional()
+        .describe('Comma-separated severities: `error`, `warn`, `info`. Default `error,warn`.'),
+    /** Case-insensitive substring of the log body (at most 200 characters; `%` and `_` are literal). */
+    q: zod_1.z
+        .string()
+        .max(constants_js_1.DASHBOARD_SEARCH_MAX_LENGTH)
+        .optional()
+        .describe('Case-insensitive substring of the log body (at most 200 characters; `%` and `_` are literal).'),
+    /** `nextCursor` of the previous page. */
+    cursor: zod_1.z
+        .string()
+        .max(constants_js_1.DASHBOARD_CURSOR_MAX)
+        .optional()
+        .describe('`nextCursor` of the previous page.'),
+})
+    .superRefine(refineWindow);
+/** `a`, `a or b`, `a, b or c`. */
+function orList(items) {
+    return items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} or ${items[items.length - 1]}`;
+}
+/**
+ * A metric group id as the contract knows it: any lower snake-case id
+ * ({@link METRIC_GROUP_ID_PATTERN}). The set is open; a server checks it
+ * against what it registered.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.metricGroupIdSchema = zod_1.z.string().regex(constants_js_1.METRIC_GROUP_ID_PATTERN);
+/**
+ * The `/metrics` `group` query value of a server with a registry: checked
+ * against the LIVE set (`isKnown`), so a group registered after the schema
+ * was built is accepted, and DOCUMENTED as the enum of `documented`, exactly
+ * as a `z.enum` would be, so the OpenAPI document reads the same.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+function metricGroupQuerySchema(options) {
+    const { documented, isKnown, knownIds } = options;
+    return zod_1.z
+        .string()
+        .refine(isKnown, {
+        error: () => `Invalid option: expected one of ${knownIds().map((id) => `"${id}"`).join('|')}`,
+    })
+        .meta({ enum: [...documented] })
+        .describe(`The metric group: ${orList(documented.map((id) => `\`${id}\``))}.`);
+}
+/**
+ * Builds the `GET …/dashboard/metrics` query schema around a `group` schema:
+ * the common query plus `group` and `host`, with {@link refineWindow}.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+function createTelemetryDashboardMetricsQuerySchema(group) {
+    return zod_1.z
+        .object({
+        ...commonShape,
+        /** The metric group: the schema passed in. */
+        group,
+        /** Only this host (`host_name`). Must be one of `/filters` `hosts` for the range. */
+        host: zod_1.z
+            .string()
+            .min(1)
+            .max(constants_js_1.DASHBOARD_FILTER_VALUE_MAX)
+            .optional()
+            .describe('Only this host (`host_name`). Must be one of `/filters` `hosts` for the range.'),
+    })
+        .superRefine(refineWindow);
+}
+/**
+ * `GET …/dashboard/metrics` query, with `group` any metric group id
+ * ({@link metricGroupIdSchema}).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardMetricsQuerySchema = createTelemetryDashboardMetricsQuerySchema(exports.metricGroupIdSchema);
+// ---- responses ---------------------------------------------------------------
+const envelope = {
+    /** Window start, ISO 8601. */
+    range: zod_1.z.object({
+        /** Window start, ISO 8601. */
+        from: zod_1.z.string().describe('Window start, ISO 8601.'),
+        /** Window end (exclusive), ISO 8601. */
+        to: zod_1.z.string().describe('Window end (exclusive), ISO 8601.'),
+        /** Bucket size used for series and sparklines. */
+        bucketSeconds: zod_1.z.number().int().describe('Bucket size used for series and sparklines.'),
+    }),
+    /** When the telemetry store was read (results are cached for 15 s). */
+    generatedAt: zod_1.z.string().describe('When the telemetry store was read (results are cached for 15 s).'),
+    /** A row cap cut a list short. */
+    truncated: zod_1.z.boolean().describe('A row cap cut a list short.'),
+    /** The exact statement(s) run, primary first. */
+    sql: zod_1.z
+        .union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())])
+        .describe('The exact statement(s) run, primary first.'),
+};
+/**
+ * The fields every dashboard response except `/metrics` starts with:
+ * `range` (`from`, `to`, `bucketSeconds`), `generatedAt`, `truncated` and
+ * `sql` (the statement or statements run, primary first).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardEnvelopeSchema = zod_1.z.object(envelope);
+const tileValue = zod_1.z.union([zod_1.z.number(), zod_1.z.string()]).nullable();
+/**
+ * One tile: `key`, `label`, `value`, `previous` (the previous window of equal
+ * length), `unit` and `sparkline` (one value per bucket, `null` a gap).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardTileSchema = zod_1.z.object({
+    /** Stable tile key. */
+    key: zod_1.z.string(),
+    /** Display label. */
+    label: zod_1.z.string(),
+    /** Current window value; null when there is nothing to measure. */
+    value: tileValue.describe('Current window value; null when there is nothing to measure.'),
+    /** Same measure over the previous window of equal length. */
+    previous: tileValue.describe('Same measure over the previous window of equal length.'),
+    /** `req/min`, `%`, `ms`, `count`, `bytes` or `timestamp`; metric tiles (`/metrics`) also use `bytes/s`, `per_s`, `per_min`, `seconds`, `hours`, `days`, `cores` and `load`. */
+    unit: zod_1.z
+        .string()
+        .describe('`req/min`, `%`, `ms`, `count`, `bytes` or `timestamp`; metric tiles (`/metrics`) also use ' +
+        '`bytes/s`, `per_s`, `per_min`, `seconds`, `hours`, `days`, `cores` and `load`.'),
+    /** One value per bucket of the window; null where unmeasurable. */
+    sparkline: zod_1.z.array(zod_1.z.number().nullable()).describe('One value per bucket of the window; null where unmeasurable.'),
+});
+/**
+ * One unknown API route of the summary (#650): `method`, the normalized
+ * `route`, `count`, and how many were `bearer` or `anonymous`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.unknownRouteSchema = zod_1.z.object({
+    /** The HTTP method, or `null`. */
+    method: zod_1.z.string().nullable(),
+    /** The request path with numeric/UUID/hex segments normalized to `:id` (a route shape, not a value). */
+    route: zod_1.z
+        .string()
+        .nullable()
+        .describe('The request path with numeric/UUID/hex segments normalized to `:id` (a route shape, not a value).'),
+    /** Requests to this unknown route in the window. */
+    count: zod_1.z.number().describe('Requests to this unknown route in the window.'),
+    /** Of those, requests carrying an `Authorization: Bearer` header (the application's own clients). */
+    bearer: zod_1.z.number().describe('Of those, requests carrying an `Authorization: Bearer` header (the application\'s own clients).'),
+    /** Of those, requests without a bearer (typically internet scanners). */
+    anonymous: zod_1.z.number().describe('Of those, requests without a bearer (typically internet scanners).'),
+});
+/**
+ * Requests to API routes that do not exist (#650): totals, the previous
+ * window's, the top routes and the statements run.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardUnknownRoutesSchema = zod_1.z
+    .object({
+    /** Requests answered by the not-found handler (404, no matched route) in the window. */
+    requests: zod_1.z.number().describe('Requests answered by the not-found handler (404, no matched route) in the window.'),
+    /** Of those, requests with an `Authorization: Bearer` header. Any of these degrades the verdict. */
+    bearer: zod_1.z.number().describe('Of those, requests with an `Authorization: Bearer` header. Any of these degrades the verdict.'),
+    /** Of those, requests without a bearer. Counted, never alarming. */
+    anonymous: zod_1.z.number().describe('Of those, requests without a bearer. Counted, never alarming.'),
+    /** `requests` over the previous window of equal length. */
+    previousRequests: zod_1.z.number().describe('`requests` over the previous window of equal length.'),
+    /** `bearer` over the previous window of equal length. */
+    previousBearer: zod_1.z.number().describe('`bearer` over the previous window of equal length.'),
+    /** Most-hit unknown routes by `METHOD /normalized-path`, bearer requests first (at most 5). */
+    topRoutes: zod_1.z
+        .array(exports.unknownRouteSchema)
+        .describe('Most-hit unknown routes by `METHOD /normalized-path`, bearer requests first (at most 5).'),
+    /** More unknown routes exist than `topRoutes` lists. */
+    truncated: zod_1.z.boolean().describe('More unknown routes exist than `topRoutes` lists.'),
+    /** The exact statements run for this block, per-route list first, then the window totals (the same text that also appears in the summary's `sql`), for "Open in Explorer". */
+    sql: zod_1.z
+        .array(zod_1.z.string())
+        .describe('The exact statements run for this block, per-route list first, then the window totals ' +
+        '(the same text that also appears in the summary\'s `sql`), for "Open in Explorer".'),
+})
+    .describe('Requests to API routes that do not exist (issue #650). Absent when the store has no ' +
+    '`span_attributes.app.route.matched` column yet (no unknown route recorded since the API started ' +
+    'writing it): the figure is then unknown, not zero.');
+/**
+ * `GET …/dashboard/summary`: the envelope plus `verdict` (`level` and
+ * `reasons`), `tiles`, `runtime` (optional) and `unknownRoutes` (optional).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardSummarySchema = zod_1.z.object({
+    ...envelope,
+    /** The overall health verdict. */
+    verdict: zod_1.z.object({
+        /** How healthy the window is. */
+        level: (0, enum_js_1.wireEnum)(constants_js_1.VERDICT_LEVELS),
+        /** Why, one line per rule that fired. */
+        reasons: zod_1.z.array(zod_1.z.string()),
+    }),
+    /** Fixed tiles: `requestsPerMin`, `errorRatePct`, `p95Ms`, `errorLogs`, `warnLogs`, `unknownRoutes` (requests to unknown API routes; value null when the store cannot tell yet, see `unknownRoutes`) and `lastDataAt`. */
+    tiles: zod_1.z
+        .array(exports.telemetryDashboardTileSchema)
+        .describe('Fixed tiles: `requestsPerMin`, `errorRatePct`, `p95Ms`, `errorLogs`, `warnLogs`, `unknownRoutes` ' +
+        '(requests to unknown API routes; value null when the store cannot tell yet, see `unknownRoutes`) and `lastDataAt`.'),
+    /** Heap used and event-loop delay p99, when the runtime metric tables exist. Not filtered by instance. */
+    runtime: zod_1.z
+        .array(exports.telemetryDashboardTileSchema)
+        .optional()
+        .describe('Heap used and event-loop delay p99, when the runtime metric tables exist. Not filtered by instance.'),
+    /** Requests to unknown API routes; absent while the store cannot tell. */
+    unknownRoutes: exports.telemetryDashboardUnknownRoutesSchema.optional(),
+});
+/**
+ * One `api` timeseries bucket: `t`, the status classes and `p95Ms`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.apiBucketSchema = zod_1.z.object({
+    /** Bucket start, ISO 8601. */
+    t: zod_1.z.string(),
+    /** 2xx responses. */
+    s2xx: zod_1.z.number(),
+    /** 3xx responses. */
+    s3xx: zod_1.z.number(),
+    /** 4xx responses. */
+    s4xx: zod_1.z.number(),
+    /** 5xx responses. */
+    s5xx: zod_1.z.number(),
+    /** 95th percentile latency in ms, or `null` with no requests. */
+    p95Ms: zod_1.z.number().nullable(),
+});
+/**
+ * One `logs` timeseries bucket: `t` and the severity bands.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.logsBucketSchema = zod_1.z.object({
+    /** Bucket start, ISO 8601. */
+    t: zod_1.z.string(),
+    /** Error-level log records. */
+    error: zod_1.z.number(),
+    /** Warn-level log records. */
+    warn: zod_1.z.number(),
+    /** Info-level log records. */
+    info: zod_1.z.number(),
+    /** Records of any other (or no) severity. */
+    other: zod_1.z.number(),
+});
+/**
+ * `GET …/dashboard/timeseries`: the envelope plus `panel` and `buckets` (api
+ * buckets for `api`, logs buckets for `logs`).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardTimeseriesSchema = zod_1.z.object({
+    ...envelope,
+    /** The panel requested. */
+    panel: (0, enum_js_1.wireEnum)(constants_js_1.DASHBOARD_PANELS),
+    /** One entry per bucket: api buckets for `api`, logs buckets for `logs`. */
+    buckets: zod_1.z.union([zod_1.z.array(exports.apiBucketSchema), zod_1.z.array(exports.logsBucketSchema)]),
+});
+/**
+ * One route of `top?kind=routes`: request counts, 5xx `errors`, 4xx
+ * `clientErrors`, `unknownRequests`, `unknown` and `p95Ms`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.topRouteSchema = zod_1.z.object({
+    /** The HTTP method, or `null`. */
+    method: zod_1.z.string().nullable(),
+    /** The request path with numeric/UUID/hex segments normalized to `:id`. */
+    route: zod_1.z.string().nullable().describe('The request path with numeric/UUID/hex segments normalized to `:id`.'),
+    /** Requests in the window. */
+    count: zod_1.z.number(),
+    /** 5xx responses. */
+    errors: zod_1.z.number().describe('5xx responses.'),
+    /** `errors` as a percentage of `count`. */
+    errorRatePct: zod_1.z.number(),
+    /** 4xx responses except 401 (an expired access token is routine), unknown routes included. */
+    clientErrors: zod_1.z.number().describe('4xx responses except 401 (an expired access token is routine), unknown routes included.'),
+    /** Requests answered by the not-found handler: no API route matches this method and path. 0 when the store cannot tell yet. */
+    unknownRequests: zod_1.z
+        .number()
+        .describe('Requests answered by the not-found handler: no API route matches this method and path. 0 when the store cannot tell yet.'),
+    /** `unknownRequests > 0`: this method + path is not a route of the running API build. */
+    unknown: zod_1.z.boolean().describe('`unknownRequests > 0`: this method + path is not a route of the running API build.'),
+    /** 95th percentile latency in ms, or `null`. */
+    p95Ms: zod_1.z.number().nullable(),
+});
+/**
+ * One error message of `top?kind=errors`: `message`, `count`, first and last
+ * seen, a sample trace and the `service`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.topErrorSchema = zod_1.z.object({
+    /** The grouped log message, or `null`. */
+    message: zod_1.z.string().nullable(),
+    /** Occurrences in the window. */
+    count: zod_1.z.number(),
+    /** First occurrence in the window, or `null`. */
+    firstSeen: zod_1.z.string().nullable(),
+    /** Last occurrence in the window, or `null`. */
+    lastSeen: zod_1.z.string().nullable(),
+    /** A trace of one occurrence, or `null`. */
+    sampleTraceId: zod_1.z.string().nullable(),
+    /** The service that logged it, or `null`. */
+    service: zod_1.z.string().nullable(),
+});
+/**
+ * `GET …/dashboard/top`: the envelope plus `kind` and `items` (routes for
+ * `routes`, errors for `errors`).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardTopSchema = zod_1.z.object({
+    ...envelope,
+    /** The kind requested. */
+    kind: (0, enum_js_1.wireEnum)(constants_js_1.DASHBOARD_TOP_KINDS),
+    /** Routes for `routes`, error messages for `errors`. */
+    items: zod_1.z.union([zod_1.z.array(exports.topRouteSchema), zod_1.z.array(exports.topErrorSchema)]),
+});
+/**
+ * One log event: `timestamp` (full precision, UTC), `severity`, `service`,
+ * `body`, `traceId` and `spanId`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.dashboardEventSchema = zod_1.z.object({
+    /** Full precision (up to nanoseconds), UTC. */
+    timestamp: zod_1.z.string().describe('Full precision (up to nanoseconds), UTC.'),
+    /** Lower-case severity text (`error`, `warn`, `info`, `debug`, …). */
+    severity: zod_1.z.string(),
+    /** The emitting service, or `null`. */
+    service: zod_1.z.string().nullable(),
+    /** The log body, or `null`. */
+    body: zod_1.z.string().nullable(),
+    /** The trace it belongs to, or `null`. */
+    traceId: zod_1.z.string().nullable(),
+    /** The span it belongs to, or `null`. */
+    spanId: zod_1.z.string().nullable(),
+});
+/**
+ * `GET …/dashboard/events`: the envelope plus `items` and `nextCursor`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardEventsSchema = zod_1.z.object({
+    ...envelope,
+    /** The events, newest first. */
+    items: zod_1.z.array(exports.dashboardEventSchema),
+    /** The `cursor` of the next page, or `null` on the last. */
+    nextCursor: zod_1.z.string().nullable(),
+});
+/**
+ * `GET …/dashboard/filters`: the envelope plus the `services`, `instances`
+ * and `hosts` seen in the window.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardFiltersSchema = zod_1.z.object({
+    ...envelope,
+    /** Services seen in the window: the values `service` accepts. */
+    services: zod_1.z.array(zod_1.z.string()),
+    /** Instances (`app.instance.id`) seen in the window: the values `instance` accepts. */
+    instances: zod_1.z.array(zod_1.z.string()),
+    /** Host names (`host_name`) seen in the host metrics — the values `/metrics` `host` accepts. */
+    hosts: zod_1.z
+        .array(zod_1.z.string())
+        .describe('Host names (`host_name`) seen in the host metrics — the values `/metrics` `host` accepts.'),
+});
+// ---- metrics (#601) ------------------------------------------------------------
+/** A unit id: a built-in one or an app's registered one (the set is open). */
+const metricUnit = presentation_js_1.metricUnitIdSchema;
+/**
+ * One point of a metric series: `t` (bucket start) and `v` (`null` where
+ * nothing was measured).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.metricPointSchema = zod_1.z.object({
+    /** Bucket start, ISO 8601. */
+    t: zod_1.z.string().describe('Bucket start, ISO 8601.'),
+    /** The value, or `null` where nothing was measured: a gap, not a zero. */
+    v: zod_1.z.number().nullable(),
+});
+/**
+ * One metric series: `key`, `label`, `unit`, `dimension`, `groupBy` and
+ * `points` (one per bucket).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.metricSeriesSchema = zod_1.z.object({
+    /** The catalog family or ratio key. */
+    key: zod_1.z.string().describe('The catalog family or ratio key.'),
+    /** Display label. */
+    label: zod_1.z.string(),
+    /** Display unit of `points`. */
+    unit: metricUnit,
+    /** The label column the family is split by (e.g. `mountpoint`), or null. */
+    dimension: zod_1.z.string().nullable().describe('The label column the family is split by (e.g. `mountpoint`), or null.'),
+    /** This series' value of `dimension` (e.g. `/`), or null. */
+    groupBy: zod_1.z.string().nullable().describe("This series' value of `dimension` (e.g. `/`), or null."),
+    /** One point per bucket of the window; null where nothing was measured. */
+    points: zod_1.z
+        .array(exports.metricPointSchema)
+        .describe('One point per bucket of the window; null where nothing was measured.'),
+});
+/**
+ * One column of a metric table: `key`, `label` and `unit`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.metricColumnSchema = zod_1.z.object({
+    /** The column key (a key of each row). */
+    key: zod_1.z.string(),
+    /** Display label. */
+    label: zod_1.z.string(),
+    /** Display unit of the column's values. */
+    unit: metricUnit,
+});
+/**
+ * One cell of a metric table row: a string, number, boolean or `null`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.metricCellSchema = zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.null()]);
+/**
+ * One per-key metric table: `key`, `label`, `columns` and `rows`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.metricTableSchema = zod_1.z.object({
+    /** The table key. */
+    key: zod_1.z.string(),
+    /** Display label. */
+    label: zod_1.z.string(),
+    /** The columns, `key` first. */
+    columns: zod_1.z.array(exports.metricColumnSchema),
+    /** One row per key; `key` holds the key column, then one entry per column. At most 50 rows (500 for `largestTables`); `truncated` says a cap cut the list. */
+    rows: zod_1.z
+        .array(zod_1.z.record(zod_1.z.string(), exports.metricCellSchema))
+        .describe('One row per key; `key` holds the key column, then one entry per column. At most 50 rows ' +
+        '(500 for `largestTables`); `truncated` says a cap cut the list.'),
+});
+/**
+ * Builds the `GET …/dashboard/metrics` response schema around a `group`
+ * schema: `range`, `generatedAt`, `truncated`, `sql`, `group`, `available`,
+ * `tiles`, `series`, `tables`, `skipped` and the optional `freshMs`.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+function createTelemetryDashboardMetricsSchema(group) {
+    return zod_1.z.object({
+        /** The window read. */
+        range: envelope.range,
+        /** When the telemetry store was read. */
+        generatedAt: envelope.generatedAt,
+        /** A series, table or histogram row cap cut a list short. */
+        truncated: zod_1.z.boolean().describe('A series, table or histogram row cap cut a list short.'),
+        /** The exact statements run, in order — for "Open in Explorer". */
+        sql: zod_1.z.array(zod_1.z.string()).describe('The exact statements run, in order — for "Open in Explorer".'),
+        /** The metric group served: the schema passed in. */
+        group,
+        /** At least one family or table of the group has its table in the store. */
+        available: zod_1.z.boolean().describe('At least one family or table of the group has its table in the store.'),
+        /** The group's tiles. */
+        tiles: zod_1.z.array(exports.telemetryDashboardTileSchema),
+        /** The group's series. */
+        series: zod_1.z.array(exports.metricSeriesSchema),
+        /** The group's per-key tables. */
+        tables: zod_1.z.array(exports.metricTableSchema),
+        /** Catalog keys (families, ratios, tables) skipped because a table or column they need is absent. */
+        skipped: zod_1.z
+            .array(zod_1.z.string())
+            .describe('Catalog keys (families, ratios, tables) skipped because a table or column they need is absent.'),
+        /** The freshness window in milliseconds: a table cell older than its table's newest reading by more than this is not current. Absent from servers that predate it. */
+        freshMs: zod_1.z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("The freshness window in milliseconds: a table cell older than its table's newest reading by more than " +
+            'this is not current. Absent from servers that predate it.'),
+    });
+}
+/**
+ * `GET …/dashboard/metrics`, with `group` any metric group id
+ * ({@link metricGroupIdSchema}).
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardMetricsSchema = createTelemetryDashboardMetricsSchema(exports.metricGroupIdSchema);
+// ---- metric groups (#680) ------------------------------------------------------
+/**
+ * One registered metric group: `id`, `label`, `title` and `order`, and, when
+ * the group declares them, its `presentation` and the descriptors of the
+ * `units` it uses that the platform does not define itself.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardMetricGroupSchema = zod_1.z.object({
+    /** The group id: the `/metrics` `group` value and the section anchor. */
+    id: zod_1.z.string().describe('The group id: the `/metrics` `group` value and the section anchor.'),
+    /** The API label (e.g. `Host`). */
+    label: zod_1.z.string().describe('The API label (e.g. `Host`).'),
+    /** The dashboard section title (e.g. `Infrastructure`). */
+    title: zod_1.z.string().describe('The dashboard section title (e.g. `Infrastructure`).'),
+    /** Dashboard order, ascending; `data` is already sorted by it (ties by id). */
+    order: zod_1.z.number().describe('Dashboard order, ascending; `data` is already sorted by it (ties by id).'),
+    /** How the section looks (data only: tiles, charts, tables, computed columns). Absent: the dashboard's defaults. */
+    presentation: presentation_js_1.metricGroupPresentationSchema
+        .optional()
+        .describe("How the section looks (data only: tiles, charts, tables, computed columns). Absent: the dashboard's defaults."),
+    /** The units the group uses that are not built in, with how to format them. */
+    units: zod_1.z
+        .array(presentation_js_1.metricUnitDescriptorSchema)
+        .optional()
+        .describe('The units the group uses that are not built in, with how to format them.'),
+});
+/**
+ * `GET …/dashboard/metric-groups`: `data`, every registered group in
+ * dashboard order.
+ *
+ * @extensionPoint schema
+ * @stability stable
+ */
+exports.telemetryDashboardMetricGroupsSchema = zod_1.z.object({
+    /** Every registered metric group (the platform's and the app's), in dashboard order. */
+    data: zod_1.z
+        .array(exports.telemetryDashboardMetricGroupSchema)
+        .describe('Every registered metric group (the platform\'s and the app\'s), in dashboard order.'),
+});
+// ---- dashboard panels (PP-14.18) -----------------------------------------------
+/**
+ * One dashboard panel the API serves: `id`, `label`, `order` and whether the
+ * platform defines it (`builtin`).
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+exports.telemetryDashboardPanelSchema = zod_1.z.object({
+    /** The panel id: the `…/panels/:id` value. */
+    id: zod_1.z.string().regex(constants_js_1.DASHBOARD_PANEL_ID_PATTERN).describe('The panel id: the `…/panels/:id` value.'),
+    /** The panel title. */
+    label: zod_1.z.string().describe('The panel title.'),
+    /** Dashboard order, ascending; `data` is already sorted by it (ties by id). */
+    order: zod_1.z.number().describe('Dashboard order, ascending; `data` is already sorted by it (ties by id).'),
+    /** `true` for the platform's own panels (`api`, `logs`). */
+    builtin: zod_1.z.boolean().describe("`true` for the platform's own panels (`api`, `logs`)."),
+});
+/**
+ * `GET …/dashboard/panels`: `data`, every registered panel in dashboard order.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+exports.telemetryDashboardPanelsSchema = zod_1.z.object({
+    /** Every registered dashboard panel, in dashboard order. */
+    data: zod_1.z.array(exports.telemetryDashboardPanelSchema).describe('Every registered dashboard panel, in dashboard order.'),
+});
+/**
+ * `GET …/dashboard/panels/:id`: the panel's `id`, when it was read and its
+ * `payload`, whatever JSON the panel's `data` function returned (at most
+ * `DASHBOARD_PANEL_PAYLOAD_MAX_BYTES` once serialised). The shape of `payload`
+ * is a contract between the app's panel and the app's view.
+ *
+ * @extensionPoint schema
+ * @stability experimental
+ */
+exports.telemetryDashboardPanelDataSchema = zod_1.z.object({
+    /** The panel id. */
+    id: zod_1.z.string().regex(constants_js_1.DASHBOARD_PANEL_ID_PATTERN).describe('The panel id.'),
+    /** When the panel was read. */
+    generatedAt: zod_1.z.string().describe('When the panel was read.'),
+    /** What the panel's data function returned (JSON). */
+    payload: zod_1.z.unknown().describe("What the panel's data function returned (JSON)."),
+});
+//# sourceMappingURL=dashboard.js.map