@ancplua/qyl-api-schema 7.3.0 → 8.0.0

package/README.md

@@ -59,6 +59,28 @@ rather than from prose here; this line moves faster than a README is revised.
 `main.tsp` is the local compile entry point and includes emitter routing. `index.tsp`
 is the published TypeSpec entry point and contains only the client-facing contract.
 
+## Runtime validation
+
+`@ancplua/qyl-api-schema/zod` builds Zod validators from the bundled JSON Schema at
+runtime. It is a translation layer over `z.fromJSONSchema` — authored in `src/zod/`
+and compiled to `generated/zod-runtime/` — not a second hand-written schema, so a
+contract change cannot leave a validator describing the previous shape.
+
+```ts
+import { publishedContractSchema } from "@ancplua/qyl-api-schema/zod";
+import type { Span } from "@ancplua/qyl-api-schema/types";
+
+const SpanSchema = publishedContractSchema<Span>("OTel.Traces.Span");
+const span = SpanSchema.parse(await response.json());
+```
+
+`zod` is an optional peer dependency (`>=4.5.0 <5`): a consumer that does not
+install it simply never imports this subpath, and the other subpaths do not depend
+on it. Definition names are the published `$defs` keys — the same names the OpenAPI
+components and the generated C# and TypeScript DTOs carry — and
+`contractDefinitionNames()` lists all of them. The type argument is not checked
+against the schema, so pair it with the matching type from `./types`.
+
 ## Contract revision
 
 `scripts/emit-contract-revision.mjs` stamps a deterministic revision — `sha256:` plus

package/api/routes.tsp

@@ -8,6 +8,7 @@ import "../otel/span.tsp";
 import "../otel/logs.tsp";
 import "../models/session.tsp";
 import "../models/health.tsp";
+import "../models/metrics.tsp";
 
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
@@ -17,6 +18,7 @@ using Qyl.Api.Contracts.Common.Errors;
 using Qyl.Api.Contracts.Common.Pagination;
 using Qyl.Api.Contracts.OTel.Traces;
 using Qyl.Api.Contracts.OTel.Logs;
+using Qyl.Api.Contracts.OTel.Metrics;
 using Qyl.Api.Contracts.OTel.Enums;
 using Qyl.Api.Contracts.Domains.Observe.Session;
 using Qyl.Api.Contracts.Health;
@@ -104,6 +106,113 @@ interface LogsApi {
     | InternalServerError;
 }
 
+// -----------------------------------------------------------------------------
+// Metrics
+//
+// Modelled on the Grafana/Prometheus range query — metric, label matchers,
+// range, step — because the primary consumer is a coding agent over MCP. The
+// collector aggregates server-side and returns buckets; raw points are never
+// served, so a payload stays small no matter how dense the underlying stream.
+// -----------------------------------------------------------------------------
+
+@route("/api/v1/metrics")
+@tag("Metrics")
+@useAuth(QylApiKeyHeaderAuth)
+interface MetricsApi {
+  @doc("List the metric names recorded for a project.")
+  @get
+  list(
+    ...ProjectScopeHeader,
+
+    @doc("Return only names starting with this prefix.")
+    @query("name_prefix")
+    namePrefix?: string,
+
+    @query
+    @minValue(1)
+    @maxValue(1000)
+    limit?: int32 = 200,
+  ):
+    | CursorPage<MetricDescriptor>
+    | ValidationError
+    | UnauthorizedError
+    | InternalServerError;
+
+  @doc("List the distinct attribute streams recorded under one metric name.")
+  @get
+  @route("/{metric_name}/series")
+  listSeries(
+    ...ProjectScopeHeader,
+    @path("metric_name") metricName: string,
+
+    @doc("""
+      Exact attribute match, repeatable, as `key=value`. A series must match
+      every matcher given.
+      """)
+    @query(#{ explode: true })
+    attr?: string[],
+
+    @doc("Attribute prefix match, repeatable, as `key=prefix`.")
+    @query(#{ name: "attr_prefix", explode: true })
+    attrPrefix?: string[],
+
+    @query
+    @minValue(1)
+    @maxValue(1000)
+    limit?: int32 = 200,
+  ):
+    | CursorPage<MetricSeries>
+    | ValidationError
+    | NotFoundError
+    | UnauthorizedError
+    | InternalServerError;
+
+  @doc("""
+    Aggregate one metric over a time range into buckets of `step_ms`.
+    Percentile aggregations require a histogram kind.
+    """)
+  @get
+  @route("/{metric_name}/query")
+  query(
+    ...ProjectScopeHeader,
+    @path("metric_name") metricName: string,
+
+    @query("start_time") startTime: utcDateTime,
+    @query("end_time") endTime: utcDateTime,
+
+    @doc("Bucket width in milliseconds. One bucket spanning the range collapses the query to a single value.")
+    @query("step_ms")
+    @minValue(1)
+    @maxValue(86400000)
+    stepMs?: int64 = 60000,
+
+    @query aggregation?: MetricAggregation = MetricAggregation.avg,
+
+    @doc("Attribute keys to split the result by, repeatable. Omitted, every matching series collapses into one stream.")
+    @query(#{ name: "group_by", explode: true })
+    groupBy?: string[],
+
+    @doc("Exact attribute match, repeatable, as `key=value`.")
+    @query(#{ explode: true })
+    attr?: string[],
+
+    @doc("Attribute prefix match, repeatable, as `key=prefix`.")
+    @query(#{ name: "attr_prefix", explode: true })
+    attrPrefix?: string[],
+
+    @doc("Maximum result streams. A grouping that exceeds this is truncated, not refused.")
+    @query("series_limit")
+    @minValue(1)
+    @maxValue(500)
+    seriesLimit?: int32 = 50,
+  ):
+    | MetricQueryResult
+    | ValidationError
+    | NotFoundError
+    | UnauthorizedError
+    | InternalServerError;
+}
+
 // -----------------------------------------------------------------------------
 // Sessions
 // -----------------------------------------------------------------------------

package/generated/json-schema/qyl-api-schema.json

@@ -3289,6 +3289,256 @@
       },
       "description": "Log message template with placeholders"
     },
+    "OTel.Metrics.MetricAggregation": {
+      "type": "string",
+      "enum": [
+        "avg",
+        "min",
+        "max",
+        "sum",
+        "count",
+        "last",
+        "p50",
+        "p90",
+        "p95",
+        "p99"
+      ],
+      "description": "Server-side reducer applied to the points falling in one time bucket."
+    },
+    "OTel.Metrics.MetricBucket": {
+      "type": "object",
+      "required": [
+        "bucket_start",
+        "value",
+        "point_count"
+      ],
+      "properties": {
+        "bucket_start": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Inclusive start of the bucket, aligned to the query's step from the query's start."
+        },
+        "value": {
+          "anyOf": [
+            {
+              "type": "number",
+              "format": "double"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The aggregation applied to the points in this bucket. Null when the bucket\nholds no value: either no point landed in it, or every point that did was\nan OTLP `NO_RECORDED_VALUE` marker."
+        },
+        "point_count": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Number of stored points folded into this bucket."
+        }
+      },
+      "unevaluatedProperties": {
+        "not": {}
+      },
+      "description": "One aggregated time bucket of a metric range query."
+    },
+    "OTel.Metrics.MetricDescriptor": {
+      "type": "object",
+      "required": [
+        "name",
+        "kind",
+        "temporality",
+        "monotonic",
+        "series_count",
+        "last_seen"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Instrument name, e.g. `http.server.request.duration`."
+        },
+        "kind": {
+          "$ref": "#/$defs/OTel.Metrics.MetricKind"
+        },
+        "temporality": {
+          "$ref": "#/$defs/OTel.Metrics.MetricTemporality"
+        },
+        "monotonic": {
+          "type": "boolean",
+          "description": "Whether a sum only ever increases. Meaningless for other kinds."
+        },
+        "unit": {
+          "type": "string",
+          "description": "UCUM unit as reported by the producer, e.g. `s` or `{request}`."
+        },
+        "description": {
+          "type": "string",
+          "description": "Producer-supplied description of the instrument."
+        },
+        "series_count": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Number of distinct attribute streams recorded under this name."
+        },
+        "last_seen": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Timestamp of the most recent point recorded under this name."
+        }
+      },
+      "unevaluatedProperties": {
+        "not": {}
+      },
+      "description": "One metric name recorded for a project, collapsed across all of its series.\nThis is the catalog entry a client reads before it knows which series exist."
+    },
+    "OTel.Metrics.MetricKind": {
+      "type": "string",
+      "enum": [
+        "gauge",
+        "sum",
+        "histogram",
+        "exponential_histogram"
+      ],
+      "description": "Shape of a stored metric stream."
+    },
+    "OTel.Metrics.MetricQueryResult": {
+      "type": "object",
+      "required": [
+        "name",
+        "kind",
+        "aggregation",
+        "step_ms",
+        "start_time",
+        "end_time",
+        "series",
+        "truncated"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Instrument name the query ran against."
+        },
+        "kind": {
+          "$ref": "#/$defs/OTel.Metrics.MetricKind"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "aggregation": {
+          "$ref": "#/$defs/OTel.Metrics.MetricAggregation"
+        },
+        "step_ms": {
+          "type": "integer",
+          "format": "int64",
+          "description": "Bucket width actually used, which may be widened from the requested step."
+        },
+        "start_time": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "end_time": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "series": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/OTel.Metrics.MetricSeriesResult"
+          }
+        },
+        "truncated": {
+          "type": "boolean",
+          "description": "Whether streams were dropped because the result exceeded the series limit."
+        }
+      },
+      "unevaluatedProperties": {
+        "not": {}
+      },
+      "description": "The answer to a metric range query: what was asked, and the streams it produced."
+    },
+    "OTel.Metrics.MetricSeries": {
+      "type": "object",
+      "required": [
+        "series_id",
+        "name",
+        "kind",
+        "attributes",
+        "first_seen",
+        "last_seen"
+      ],
+      "properties": {
+        "series_id": {
+          "type": "string",
+          "description": "Stable identifier for this stream, derived from its name, attributes and resource."
+        },
+        "name": {
+          "type": "string",
+          "description": "Instrument name this series belongs to."
+        },
+        "kind": {
+          "$ref": "#/$defs/OTel.Metrics.MetricKind"
+        },
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Common.Attribute"
+          },
+          "description": "The attributes that distinguish this series from others under the same name."
+        },
+        "service_name": {
+          "type": "string"
+        },
+        "unit": {
+          "type": "string"
+        },
+        "first_seen": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "last_seen": {
+          "type": "string",
+          "format": "date-time"
+        }
+      },
+      "unevaluatedProperties": {
+        "not": {}
+      },
+      "description": "One distinct attribute stream recorded under a metric name."
+    },
+    "OTel.Metrics.MetricSeriesResult": {
+      "type": "object",
+      "required": [
+        "attributes",
+        "buckets"
+      ],
+      "properties": {
+        "attributes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Common.Attribute"
+          },
+          "description": "The grouping key that produced this stream."
+        },
+        "buckets": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/OTel.Metrics.MetricBucket"
+          }
+        }
+      },
+      "unevaluatedProperties": {
+        "not": {}
+      },
+      "description": "One result stream of a metric range query. With no `group_by` the whole\nresult is a single stream whose `attributes` are empty; with `group_by` there\nis one stream per distinct combination of the requested attribute values."
+    },
+    "OTel.Metrics.MetricTemporality": {
+      "type": "string",
+      "enum": [
+        "unspecified",
+        "delta",
+        "cumulative"
+      ],
+      "description": "How successive points of a sum or histogram relate to each other."
+    },
     "OTel.Resource.CloudProvider": {
       "type": "string",
       "enum": [
@@ -8071,6 +8321,106 @@
     "Operations.LogsApi_list.Response.500": {
       "$ref": "#/$defs/Common.Errors.InternalServerError"
     },
+    "Operations.MetricsApi_list.Response.200": {
+      "type": "object",
+      "required": [
+        "items",
+        "has_more"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/OTel.Metrics.MetricDescriptor"
+          },
+          "description": "List of items in this page"
+        },
+        "next_cursor": {
+          "type": "string",
+          "description": "Cursor for the next page (null if no more pages)"
+        },
+        "prev_cursor": {
+          "type": "string",
+          "description": "Cursor for the previous page (null if first page)"
+        },
+        "has_more": {
+          "type": "boolean",
+          "description": "Whether there are more items available"
+        }
+      },
+      "unevaluatedProperties": {
+        "not": {}
+      },
+      "description": "Cursor-based paginated response wrapper"
+    },
+    "Operations.MetricsApi_list.Response.400": {
+      "$ref": "#/$defs/Common.Errors.ValidationError"
+    },
+    "Operations.MetricsApi_list.Response.401": {
+      "$ref": "#/$defs/Common.Errors.UnauthorizedError"
+    },
+    "Operations.MetricsApi_list.Response.500": {
+      "$ref": "#/$defs/Common.Errors.InternalServerError"
+    },
+    "Operations.MetricsApi_listSeries.Response.200": {
+      "type": "object",
+      "required": [
+        "items",
+        "has_more"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/OTel.Metrics.MetricSeries"
+          },
+          "description": "List of items in this page"
+        },
+        "next_cursor": {
+          "type": "string",
+          "description": "Cursor for the next page (null if no more pages)"
+        },
+        "prev_cursor": {
+          "type": "string",
+          "description": "Cursor for the previous page (null if first page)"
+        },
+        "has_more": {
+          "type": "boolean",
+          "description": "Whether there are more items available"
+        }
+      },
+      "unevaluatedProperties": {
+        "not": {}
+      },
+      "description": "Cursor-based paginated response wrapper"
+    },
+    "Operations.MetricsApi_listSeries.Response.400": {
+      "$ref": "#/$defs/Common.Errors.ValidationError"
+    },
+    "Operations.MetricsApi_listSeries.Response.401": {
+      "$ref": "#/$defs/Common.Errors.UnauthorizedError"
+    },
+    "Operations.MetricsApi_listSeries.Response.404": {
+      "$ref": "#/$defs/Common.Errors.NotFoundError"
+    },
+    "Operations.MetricsApi_listSeries.Response.500": {
+      "$ref": "#/$defs/Common.Errors.InternalServerError"
+    },
+    "Operations.MetricsApi_query.Response.200": {
+      "$ref": "#/$defs/OTel.Metrics.MetricQueryResult"
+    },
+    "Operations.MetricsApi_query.Response.400": {
+      "$ref": "#/$defs/Common.Errors.ValidationError"
+    },
+    "Operations.MetricsApi_query.Response.401": {
+      "$ref": "#/$defs/Common.Errors.UnauthorizedError"
+    },
+    "Operations.MetricsApi_query.Response.404": {
+      "$ref": "#/$defs/Common.Errors.NotFoundError"
+    },
+    "Operations.MetricsApi_query.Response.500": {
+      "$ref": "#/$defs/Common.Errors.InternalServerError"
+    },
     "Operations.RunnerResourcesApi_logs.Response.200": {
       "type": "array",
       "items": {