@shipeasy/openapi 3.2.0 → 3.3.0

package/spec/components/schemas/metrics.yaml

@@ -186,252 +186,38 @@ GetMetricResponse:
   additionalProperties: {}
   description: A metric definition.
 QueryIr:
-  description: Typed query IR — the structured alternative to the `query` DSL string. Exactly one of `query` / `query_ir` is supplied per metric body.
+  description: >-
+    A metric definition as a typed expression tree — the structured alternative
+    to the `query` DSL string, and what the API stores. Exactly one of `query` /
+    `query_ir` is supplied per metric body; `query` is the same definition
+    written as text, and is the spelling to prefer.
+
+    Until 2026-08-10 this documented a single aggregation (`{agg, metric,
+    filters}`, with `ratio` as a special case). That shape no longer exists —
+    stored metrics were migrated and the code that read it was deleted — so a
+    body sending it is rejected. Send the `query` string instead, or the tree
+    below.
   type: object
   properties:
-    agg:
-      oneOf:
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: count_users
-          required:
-            - kind
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: count_events
-          required:
-            - kind
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: sum
-          required:
-            - kind
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: avg
-          required:
-            - kind
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: min
-          required:
-            - kind
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: max
-          required:
-            - kind
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: unique
-          required:
-            - kind
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: quantile
-            p:
-              anyOf:
-                - type: number
-                  const: 0.5
-                - type: number
-                  const: 0.75
-                - type: number
-                  const: 0.9
-                - type: number
-                  const: 0.95
-                - type: number
-                  const: 0.99
-                - type: number
-                  const: 0.999
-              description: Quantile fraction (0.5 = p50 … 0.999 = p999).
-          required:
-            - kind
-            - p
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: retention_Nd
-            n:
-              type: integer
-              minimum: 1
-              maximum: 90
-              description: Retention window in days (1–90).
-          required:
-            - kind
-            - n
-          additionalProperties: false
-        - type: object
-          properties:
-            kind:
-              type: string
-              const: ratio
-            numerator:
-              type: object
-              properties:
-                agg:
-                  type: string
-                  enum:
-                    - count_users
-                    - count_events
-                  description: Counting mode for this ratio arm.
-                metric:
-                  type: string
-                  minLength: 1
-                  maxLength: 128
-                  description: Source event name for this ratio arm.
-                filters:
-                  description: Optional label filters.
-                  maxItems: 16
-                  type: array
-                  items:
-                    type: object
-                    properties:
-                      label:
-                        type: string
-                        pattern: ^[a-z_][a-z0-9_]{0,63}$
-                        description: Event property / label identifier.
-                      op:
-                        type: string
-                        enum:
-                          - =
-                          - "!="
-                          - =~
-                          - "!~"
-                        description: Match operator (`=~`/`!~` are regex).
-                      value:
-                        type: string
-                        maxLength: 512
-                        description: Quoted filter value (coerced for numeric labels).
-                    required:
-                      - label
-                      - op
-                      - value
-                    additionalProperties: false
-                    description: One label filter on the source event.
-              required:
-                - agg
-                - metric
-              additionalProperties: false
-              description: Numerator or denominator arm of a `ratio` aggregation.
-            denominator:
-              type: object
-              properties:
-                agg:
-                  type: string
-                  enum:
-                    - count_users
-                    - count_events
-                  description: Counting mode for this ratio arm.
-                metric:
-                  type: string
-                  minLength: 1
-                  maxLength: 128
-                  description: Source event name for this ratio arm.
-                filters:
-                  description: Optional label filters.
-                  maxItems: 16
-                  type: array
-                  items:
-                    type: object
-                    properties:
-                      label:
-                        type: string
-                        pattern: ^[a-z_][a-z0-9_]{0,63}$
-                        description: Event property / label identifier.
-                      op:
-                        type: string
-                        enum:
-                          - =
-                          - "!="
-                          - =~
-                          - "!~"
-                        description: Match operator (`=~`/`!~` are regex).
-                      value:
-                        type: string
-                        maxLength: 512
-                        description: Quoted filter value (coerced for numeric labels).
-                    required:
-                      - label
-                      - op
-                      - value
-                    additionalProperties: false
-                    description: One label filter on the source event.
-              required:
-                - agg
-                - metric
-              additionalProperties: false
-              description: Numerator or denominator arm of a `ratio` aggregation.
-          required:
-            - kind
-            - numerator
-            - denominator
-          additionalProperties: false
-      description: Aggregation function applied to the source event.
-    metric:
-      type: string
-      minLength: 1
-      maxLength: 128
-      description: Source event name (must equal `event_name`).
-    valueLabel:
-      description: Numeric property summed/averaged for `sum`/`avg`/quantile aggregations.
-      type: string
-      minLength: 1
-      maxLength: 128
-    filters:
-      default: []
-      description: Label filters on the event.
-      maxItems: 16
-      type: array
-      items:
-        type: object
-        properties:
-          label:
-            type: string
-            pattern: ^[a-z_][a-z0-9_]{0,63}$
-            description: Event property / label identifier.
-          op:
-            type: string
-            enum:
-              - =
-              - "!="
-              - =~
-              - "!~"
-            description: Match operator (`=~`/`!~` are regex).
-          value:
-            type: string
-            maxLength: 512
-            description: Quoted filter value (coerced for numeric labels).
-        required:
-          - label
-          - op
-          - value
-        additionalProperties: false
-        description: One label filter on the source event.
+    v:
+      type: integer
+      const: 2
+      description: Storage version of the definition. `2` is the only one.
+    expr:
+      type: object
+      additionalProperties: true
+      description: >-
+        The expression tree: aggregate leaves (`{node: "agg", event, agg,
+        filters, valueLabel?}`), arithmetic over them (`{node: "binary", op,
+        left, right}`), scalars, and function calls (`{node: "call", fn, arg,
+        params?}`). A ratio is ordinary division of two leaves.
+
+        Deliberately opaque here rather than mirrored node by node: the grammar
+        belongs to the query language, a second copy of it in this spec would
+        drift from the one the server enforces, and the server validates every
+        tree by planning it before the metric saves. `GET /api/admin/metrics`
+        returns the grammar itself; the `query` string is the same tree in the
+        form humans and the CLI write.
     groupBy:
       type: object
       properties:
@@ -440,23 +226,27 @@ QueryIr:
           enum:
             - by
             - without
-          description: "`by` keeps the listed labels; `without` drops them."
+          description: "`by` names the output dimensions; `without` names the ones to drop."
         labels:
-          maxItems: 5
           type: array
+          maxItems: 8
           items:
             type: string
             pattern: ^[a-z_][a-z0-9_]{0,63}$
             description: Event property / label identifier.
-          description: Labels to group by (max 5).
+          description: Labels the grouping names.
       required:
         - op
         - labels
       additionalProperties: false
-      description: Optional group-by clause (ignored for experiment analysis).
+      description: >-
+        How the series is split. On the envelope rather than in `expr` because
+        every leaf of one expression shares it.
+    display:
+      $ref: "#/MetricDisplayConfig"
   required:
-    - agg
-    - metric
+    - v
+    - expr
   additionalProperties: false
 MetricEventName:
   type: string
@@ -492,6 +282,68 @@ MetricDisplayUnit:
   anyOf:
     - type: string
     - type: "null"
+MetricDisplayName:
+  description: >-
+    What a human calls the metric — "Checkout revenue" beside the
+    `checkout.revenue` that identifies it. Unlike `name` it is free text, it is
+    editable, and nothing addresses the metric by it: the dashboard leads with it
+    and falls back to `name` when it is absent, so a metric nobody named simply
+    reads as its key. Send `null` to clear it.
+  maxLength: 200
+  anyOf:
+    - type: string
+    - type: "null"
+MetricDisplayConfig:
+  description: >-
+    How the metric's series is DRAWN, as opposed to what it measures. Both parts
+    used to be DSL functions (`expected(q, seasonal)`, `forecast(q, …)`), which
+    meant turning a band on minted a different metric; they are properties now,
+    so every chart of the metric picks them up and nothing that JUDGES the metric
+    — an alert rule, the experiment analyzer — reads them at all.
+  type: object
+  properties:
+    band:
+      description: >-
+        Shade the seasonal baseline around the series. The fit is the median of
+        this hour of the week over the four weeks before the window, and it is
+        the SAME fit an `anomaly` alert rule fires on — so the shaded region is
+        exactly where such a rule would stay quiet, whether or not one exists.
+      type: object
+      properties:
+        method:
+          type: string
+          enum:
+            - seasonal
+        sigma:
+          type: number
+          exclusiveMinimum: 0
+          description: Half-width of the band in sigma-equivalents. Omit for 3, the sigma an alert rule also defaults to.
+      required:
+        - method
+      additionalProperties: false
+    forecast:
+      description: Project the series past the end of the window. Projected buckets are marked, so a chart can draw an estimate differently from a measurement.
+      type: object
+      properties:
+        method:
+          type: string
+          enum:
+            - linear
+            - seasonal
+          description: >-
+            `linear` continues a least-squares slope over the window it is
+            already reading. `seasonal` de-seasonalises against the four weeks
+            before the window, fits the trend on the remainder and adds the
+            hour-of-week term back — ask for it when the metric has a shape.
+        horizon:
+          type: integer
+          minimum: 1
+          maximum: 500
+          description: Buckets to project. Omit for a quarter of the window, which is the same claim at every bucket width.
+      required:
+        - method
+      additionalProperties: false
+  additionalProperties: false
 CreateMetricRequest:
   oneOf:
     - $ref: "#/CreateMetricWithQuery"
@@ -502,6 +354,8 @@ CreateMetricWithQuery:
   properties:
     name:
       $ref: ./common.yaml#/MetricName
+    display_name:
+      $ref: "#/MetricDisplayName"
     folder:
       $ref: ./common.yaml#/Folder
     event_name:
@@ -516,6 +370,8 @@ CreateMetricWithQuery:
       $ref: "#/MetricDirection"
     unit:
       $ref: "#/MetricDisplayUnit"
+    display:
+      $ref: "#/MetricDisplayConfig"
   required:
     - name
     - event_name
@@ -527,6 +383,8 @@ CreateMetricWithQueryIr:
   properties:
     name:
       $ref: ./common.yaml#/MetricName
+    display_name:
+      $ref: "#/MetricDisplayName"
     folder:
       $ref: ./common.yaml#/Folder
     event_name:
@@ -541,6 +399,8 @@ CreateMetricWithQueryIr:
       $ref: "#/MetricDirection"
     unit:
       $ref: "#/MetricDisplayUnit"
+    display:
+      $ref: "#/MetricDisplayConfig"
   required:
     - name
     - event_name
@@ -556,6 +416,8 @@ UpdateMetricRequest:
 UpdateMetricWithQuery:
   type: object
   properties:
+    display_name:
+      $ref: "#/MetricDisplayName"
     folder:
       $ref: ./common.yaml#/Folder
     event_name:
@@ -570,6 +432,8 @@ UpdateMetricWithQuery:
       $ref: "#/MetricDirection"
     unit:
       $ref: "#/MetricDisplayUnit"
+    display:
+      $ref: "#/MetricDisplayConfig"
   required:
     - query
   additionalProperties: false
@@ -577,6 +441,8 @@ UpdateMetricWithQuery:
 UpdateMetricWithQueryIr:
   type: object
   properties:
+    display_name:
+      $ref: "#/MetricDisplayName"
     folder:
       $ref: ./common.yaml#/Folder
     event_name:
@@ -591,6 +457,8 @@ UpdateMetricWithQueryIr:
       $ref: "#/MetricDirection"
     unit:
       $ref: "#/MetricDisplayUnit"
+    display:
+      $ref: "#/MetricDisplayConfig"
   required:
     - query_ir
   additionalProperties: false
@@ -598,6 +466,8 @@ UpdateMetricWithQueryIr:
 UpdateMetricFields:
   type: object
   properties:
+    display_name:
+      $ref: "#/MetricDisplayName"
     folder:
       $ref: ./common.yaml#/Folder
     event_name:
@@ -610,8 +480,10 @@ UpdateMetricFields:
       $ref: "#/MetricDirection"
     unit:
       $ref: "#/MetricDisplayUnit"
+    display:
+      $ref: "#/MetricDisplayConfig"
   additionalProperties: false
-  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit).
+  description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit, band and projection).
 CreateMetricResponse:
   type: object
   properties:
@@ -729,6 +601,14 @@ GetMetricSeriesResponse:
           v:
             type: number
             description: Aggregated metric value in the bucket (sample-interval weighted).
+          lo:
+            type: number
+            description: |
+              Lower edge of the seasonal band — what this hour of the week normally holds, `sigma` below the median of the four weeks before the window. Present only for a metric whose `display.band` is on, and always alongside `hi`.
+          hi:
+            type: number
+            description: |
+              Upper edge of the seasonal band. Present only for a metric whose `display.band` is on, and always alongside `lo`. A point outside `[lo, hi]` is exactly a bucket an `anomaly` alert rule at the same sigma would breach on — the band a chart draws and the condition a rule fires on come from one fit.
         required:
           - t
           - v