@ancplua/qyl-api-schema 11.5.0 → 11.6.0-rc.1

package/models/metrics.tsp

@@ -0,0 +1,198 @@
+import "../common/types.tsp";
+
+using Qyl.Api.Contracts.Common;
+
+namespace Qyl.Api.Contracts.OTel.Metrics;
+
+@doc("Shape of a stored metric stream.")
+enum MetricKind {
+  @doc("A value sampled at a point in time.")
+  gauge: "gauge",
+
+  @doc("An additive value; see `temporality` and `monotonic` for how to read it.")
+  sum: "sum",
+
+  @doc("A distribution recorded against explicit bucket boundaries.")
+  histogram: "histogram",
+
+  @doc("""
+    An OTLP exponential histogram. Its buckets are stored in the same explicit
+    bound vector `histogram` uses, so both kinds answer the same queries; the
+    distinct name records only where the distribution came from.
+    """)
+  exponential_histogram: "exponential_histogram",
+}
+
+@doc("How successive points of a sum or histogram relate to each other.")
+enum MetricTemporality {
+  unspecified: "unspecified",
+
+  @doc("Each point covers only the interval since the previous one.")
+  delta: "delta",
+
+  @doc("Each point is the running total since the stream's start time.")
+  cumulative: "cumulative",
+}
+
+@doc("Server-side reducer applied to the points falling in one time bucket.")
+enum MetricAggregation {
+  avg: "avg",
+  min: "min",
+  max: "max",
+  sum: "sum",
+  count: "count",
+
+  @doc("The value of the latest point in the bucket.")
+  last: "last",
+
+  @doc("50th percentile, interpolated from bucket boundaries. Histogram kinds only.")
+  p50: "p50",
+
+  @doc("90th percentile, interpolated from bucket boundaries. Histogram kinds only.")
+  p90: "p90",
+
+  @doc("95th percentile, interpolated from bucket boundaries. Histogram kinds only.")
+  p95: "p95",
+
+  @doc("99th percentile, interpolated from bucket boundaries. Histogram kinds only.")
+  p99: "p99",
+}
+
+@doc("""
+  One metric name recorded for a project, collapsed across all of its series.
+  This is the catalog entry a client reads before it knows which series exist.
+  """)
+model MetricDescriptor {
+  @doc("Instrument name, e.g. `http.server.request.duration`.")
+  name: string;
+
+  kind: MetricKind;
+
+  temporality: MetricTemporality;
+
+  @doc("Whether a sum only ever increases. Meaningless for other kinds.")
+  monotonic: boolean;
+
+  @doc("UCUM unit as reported by the producer, e.g. `s` or `{request}`.")
+  unit?: string;
+
+  @doc("Producer-supplied description of the instrument.")
+  description?: string;
+
+  @doc("Number of distinct attribute streams recorded under this name.")
+  @encodedName("application/json", "series_count")
+  seriesCount: int64;
+
+  @doc("Timestamp of the most recent point recorded under this name.")
+  @encodedName("application/json", "last_seen")
+  lastSeen: utcDateTime;
+}
+
+@doc("One distinct attribute stream recorded under a metric name.")
+model MetricSeries {
+  @doc("Stable identifier for this stream, derived from its name, attributes and resource.")
+  @encodedName("application/json", "series_id")
+  seriesId: string;
+
+  @doc("Instrument name this series belongs to.")
+  name: string;
+
+  kind: MetricKind;
+
+  @doc("The attributes that distinguish this series from others under the same name.")
+  attributes: Attribute[];
+
+  @encodedName("application/json", "service_name")
+  serviceName?: string;
+
+  unit?: string;
+
+  @encodedName("application/json", "first_seen")
+  firstSeen: utcDateTime;
+
+  @encodedName("application/json", "last_seen")
+  lastSeen: utcDateTime;
+}
+
+@doc("One aggregated time bucket of a metric range query.")
+model MetricBucket {
+  @doc("Inclusive start of the bucket, aligned to the query's step from the query's start.")
+  @encodedName("application/json", "bucket_start")
+  bucketStart: utcDateTime;
+
+  @doc("""
+    The aggregation applied to the points in this bucket. Null when the bucket
+    holds no value: either no point landed in it, or every point that did was
+    an OTLP `NO_RECORDED_VALUE` marker.
+    """)
+  value: float64 | null;
+
+  @doc("Number of stored points folded into this bucket.")
+  @encodedName("application/json", "point_count")
+  pointCount: int64;
+}
+
+@doc("""
+  One result stream of a metric range query. With no `group_by` the whole
+  result is a single stream whose `attributes` are empty; with `group_by` there
+  is one stream per distinct combination of the requested attribute values.
+  """)
+model MetricSeriesResult {
+  @doc("The grouping key that produced this stream.")
+  attributes: Attribute[];
+
+  buckets: MetricBucket[];
+}
+
+@doc("The answer to a metric range query: what was asked, and the streams it produced.")
+model MetricQueryResult {
+  @doc("Instrument name the query ran against.")
+  name: string;
+
+  kind: MetricKind;
+
+  unit?: string;
+
+  aggregation: MetricAggregation;
+
+  @doc("Bucket width actually used, which may be widened from the requested step.")
+  @encodedName("application/json", "step_ms")
+  stepMs: int64;
+
+  @encodedName("application/json", "start_time")
+  startTime: utcDateTime;
+
+  @encodedName("application/json", "end_time")
+  endTime: utcDateTime;
+
+  series: MetricSeriesResult[];
+
+  @doc("Whether streams were dropped because the result exceeded the series limit.")
+  truncated: boolean;
+}
+
+@doc("How a structured attribute matcher compares an attribute value.")
+enum MetricMatcherOp {
+  @doc("The attribute equals `value`; serialized to the `attr` query parameter as `key=value`.")
+  eq: "eq",
+
+  @doc("The attribute starts with `value`; serialized to the `attr_prefix` query parameter as `key=value`.")
+  prefix: "prefix",
+}
+
+@doc("""
+  One structured attribute matcher. Tool inputs and saved queries carry
+  matchers in this form; the HTTP routes keep their `key=value` string
+  parameters, and a client serializes each matcher to one of them.
+  """)
+model MetricAttributeMatcher {
+  @doc("Attribute key, e.g. `http.route`.")
+  @minLength(1)
+  @maxLength(256)
+  key: string;
+
+  `op`: MetricMatcherOp;
+
+  @maxLength(1024)
+  value: string;
+}

package/models/saved-queries.tsp

@@ -0,0 +1,212 @@
+// =============================================================================
+// Saved queries: named, structured filters for traces, logs or metrics
+// =============================================================================
+// A saved query stores a filter, never results. `:run` evaluates it against
+// the current telemetry with a window relative to the time of the run.
+// Names are unique per project; a duplicate is refused with 409.
+// =============================================================================
+
+import "@typespec/http";
+import "@typespec/openapi";
+import "../common/types.tsp";
+import "../common/resource.tsp";
+import "../otel/enums.tsp";
+import "../otel/span.tsp";
+import "../otel/logs.tsp";
+import "./metrics.tsp";
+
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Enums;
+using Qyl.Api.Contracts.OTel.Logs;
+using Qyl.Api.Contracts.OTel.Metrics;
+using Qyl.Api.Contracts.OTel.Traces;
+
+namespace Qyl.Api.Contracts.SavedQueries;
+
+@doc("The telemetry signal a saved query reads.")
+enum SavedQuerySignal {
+  traces: "traces",
+  logs: "logs",
+  metrics: "metrics",
+}
+
+@doc("Look-back window shared by every saved-query filter.")
+model SavedQueryWindow {
+  @doc("Window ending at the time of the run, in minutes. Omitted, the run's own `start_time`/`end_time` or the last 60 minutes apply.")
+  @encodedName("application/json", "lookback_minutes")
+  @minValue(1)
+  @maxValue(43200)
+  lookbackMinutes?: int32;
+}
+
+@doc("A saved filter over traces.")
+model SavedTraceQueryFilter {
+  signal: "traces";
+  ...SavedQueryWindow;
+
+  @encodedName("application/json", "service_name")
+  @minLength(1)
+  @maxLength(256)
+  serviceName?: string;
+
+  @doc("Keep only traces with at least one error span.")
+  @encodedName("application/json", "errors_only")
+  errorsOnly?: boolean;
+}
+
+@doc("A saved filter over log records.")
+model SavedLogQueryFilter {
+  signal: "logs";
+  ...SavedQueryWindow;
+
+  @encodedName("application/json", "service_name")
+  @minLength(1)
+  @maxLength(256)
+  serviceName?: string;
+
+  @encodedName("application/json", "severity_min")
+  severityMin?: SeverityNumber;
+
+  @encodedName("application/json", "session_id")
+  sessionId?: SessionId;
+
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+
+  @doc("Substring searched in the log body.")
+  @minLength(1)
+  @maxLength(1024)
+  query?: string;
+}
+
+@doc("A saved metric range query.")
+model SavedMetricQueryFilter {
+  signal: "metrics";
+  ...SavedQueryWindow;
+
+  @encodedName("application/json", "metric_name")
+  @minLength(1)
+  @maxLength(256)
+  metricName: string;
+
+  aggregation?: MetricAggregation = MetricAggregation.avg;
+
+  @doc("Bucket width in integer milliseconds.")
+  @encodedName("application/json", "step_ms")
+  @minValue(1)
+  @maxValue(86400000)
+  stepMs?: int64 = 60000;
+
+  @doc("Attribute keys to split the result by.")
+  @encodedName("application/json", "group_by")
+  @maxItems(16)
+  groupBy?: string[];
+
+  @doc("Attribute matchers a series must all satisfy.")
+  @maxItems(32)
+  matchers?: MetricAttributeMatcher[];
+}
+
+@doc("Exactly one structured filter; `signal` selects which.")
+@oneOf
+union SavedQueryFilter {
+  traces: SavedTraceQueryFilter,
+  logs: SavedLogQueryFilter,
+  metrics: SavedMetricQueryFilter,
+}
+
+@doc("A named filter for traces, logs or metrics, owned by one project.")
+model SavedQuery extends ResourceBase {
+  @doc("Unique within the project; a duplicate is refused with 409.")
+  @minLength(1)
+  @maxLength(200)
+  name: string;
+
+  @maxLength(2000)
+  description?: string;
+
+  filter: SavedQueryFilter;
+}
+
+@doc("Body of POST /api/v1/saved-queries: the `Lifecycle.Create` members of SavedQuery.")
+model SavedQueryCreateRequest {
+  @doc("Unique within the project; a duplicate is refused with 409.")
+  @minLength(1)
+  @maxLength(200)
+  name: string;
+
+  @maxLength(2000)
+  description?: string;
+
+  filter: SavedQueryFilter;
+}
+
+@doc("Body of PATCH /api/v1/saved-queries/{saved_query_id}: the `Lifecycle.Update` members of SavedQuery, each optional; omitted members keep their value.")
+model SavedQueryUpdateRequest {
+  @doc("New name, unique within the project; a duplicate is refused with 409.")
+  @minLength(1)
+  @maxLength(200)
+  name?: string;
+
+  @maxLength(2000)
+  description?: string;
+
+  filter?: SavedQueryFilter;
+}
+
+@doc("Optional overrides for one run of a saved query.")
+model SavedQueryRunRequest {
+  @doc("Overrides the saved look-back window together with `end_time`.")
+  @encodedName("application/json", "start_time")
+  startTime?: utcDateTime;
+
+  @encodedName("application/json", "end_time")
+  endTime?: utcDateTime;
+
+  @doc("Page size for trace and log runs.")
+  @minValue(1)
+  @maxValue(1000)
+  limit?: int32 = 100;
+
+  @doc("`next_cursor` of a previous run of the same saved query.")
+  cursor?: Cursor;
+}
+
+@doc("One page of trace summaries produced by a saved trace query, like list_traces; get_trace reads one full span tree.")
+model SavedTraceQueryRun {
+  signal: "traces";
+  items: TraceSummary[];
+
+  @encodedName("application/json", "next_cursor")
+  nextCursor?: Cursor;
+
+  @encodedName("application/json", "has_more")
+  hasMore: boolean;
+}
+
+@doc("One page of log records produced by a saved log query.")
+model SavedLogQueryRun {
+  signal: "logs";
+  items: LogRecord[];
+
+  @encodedName("application/json", "next_cursor")
+  nextCursor?: Cursor;
+
+  @encodedName("application/json", "has_more")
+  hasMore: boolean;
+}
+
+@doc("The range-query result produced by a saved metric query.")
+model SavedMetricQueryRun {
+  signal: "metrics";
+  result: MetricQueryResult;
+}
+
+@doc("The result of running a saved query; `signal` matches the query's filter.")
+@oneOf
+union SavedQueryRunResult {
+  traces: SavedTraceQueryRun,
+  logs: SavedLogQueryRun,
+  metrics: SavedMetricQueryRun,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "11.5.0",
+  "version": "11.6.0-rc.1",
   "description": "TypeSpec source of truth for qyl API contracts. Emits OpenAPI, JSON Schema, Qyl.Api.Contracts DTOs, and TypeScript contract types; not an OpenTelemetry package, storage schema, or server implementation.",
   "license": "Apache-2.0",
   "workspaces": [
@@ -65,14 +65,19 @@
     "api/runner.tsp",
     "api/streaming.tsp",
     "api/workbench.tsp",
+    "common/auth.tsp",
     "common/errors.tsp",
     "common/pagination.tsp",
     "common/types.tsp",
+    "common/resource.tsp",
     "models/health.tsp",
+    "models/metrics.tsp",
     "models/runner.tsp",
     "models/workbench.tsp",
+    "models/annotations.tsp",
     "models/mcp-tools.tsp",
     "models/session.tsp",
+    "models/saved-queries.tsp",
     "otel/enums.tsp",
     "otel/logs.tsp",
     "otel/otel-conventions.tsp",