Oxide System/metrics API

openapi: 3.2.0
info:
  title: Oxide Region System/metrics API
  description: API for interacting with the Oxide control plane
  contact:
    url: https://oxide.computer
    email: api@oxide.computer
  version: 2026081901.0.0
tags:
- name: system/metrics
  description: Metrics provide insight into the operation of the Oxide deployment. These include telemetry on hardware and software components that can be used to understand the current state as well as to diagnose issues.
  externalDocs:
    url: http://docs.oxide.computer/api/system-metrics
paths:
  /v1/system/metrics/{metric_name}:
    get:
      tags:
      - system/metrics
      summary: View metrics
      description: View CPU, memory, or storage utilization metrics at the fleet or silo level.
      operationId: system_metric
      parameters:
      - in: path
        name: metric_name
        required: true
        schema:
          $ref: '#/components/schemas/SystemMetricName'
      - in: query
        name: end_time
        description: An exclusive end time of metrics.
        schema:
          type: string
          format: date-time
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: order
        description: Query result order
        schema:
          $ref: '#/components/schemas/PaginationOrder'
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      - in: query
        name: start_time
        description: An inclusive start time of metrics.
        schema:
          type: string
          format: date-time
      - in: query
        name: silo
        description: Name or ID of the silo
        schema:
          $ref: '#/components/schemas/NameOrId'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MeasurementResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required:
        - end_time
        - start_time
  /v1/system/timeseries/query:
    post:
      tags:
      - system/metrics
      summary: Run timeseries query
      description: Queries are written in OxQL.
      operationId: system_timeseries_query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TimeseriesQuery'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OxqlQueryResult'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
  /v1/system/timeseries/schemas:
    get:
      tags:
      - system/metrics
      summary: List timeseries schemas
      operationId: system_timeseries_schema_list
      parameters:
      - in: query
        name: limit
        description: Maximum number of items returned by a single call
        schema:
          type:
          - integer
          - 'null'
          format: uint32
          minimum: 1
      - in: query
        name: page_token
        description: Token returned by previous call to retrieve the subsequent page
        schema:
          type:
          - string
          - 'null'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimeseriesSchemaResultsPage'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      x-dropshot-pagination:
        required: []
components:
  schemas:
    Binuint16:
      description: Type storing bin edges and a count of samples within it.
      type: object
      properties:
        count:
          description: The total count of samples in this bin.
          type: integer
          format: uint64
          minimum: 0
        range:
          description: The range of the support covered by this bin.
          allOf:
          - $ref: '#/components/schemas/BinRangeuint16'
      required:
      - count
      - range
    Values:
      description: A single list of values, for one dimension of a timeseries.
      type: object
      properties:
        metric_type:
          description: The type of this metric.
          allOf:
          - $ref: '#/components/schemas/MetricType'
        values:
          description: The data values.
          allOf:
          - $ref: '#/components/schemas/ValueArray'
      required:
      - metric_type
      - values
    BinRangeint16:
      description: 'A type storing a range over `T`.


        This type supports ranges similar to the `RangeTo`, `Range` and `RangeFrom` types in the standard library. Those cover `(..end)`, `(start..end)`, and `(start..)` respectively.'
      oneOf:
      - description: A range unbounded below and exclusively above, `..end`.
        type: object
        properties:
          end:
            type: integer
            format: int16
          type:
            type: string
            enum:
            - range_to
        required:
        - end
        - type
      - description: A range bounded inclusively below and exclusively above, `start..end`.
        type: object
        properties:
          end:
            type: integer
            format: int16
          start:
            type: integer
            format: int16
          type:
            type: string
            enum:
            - range
        required:
        - end
        - start
        - type
      - description: A range bounded inclusively below and unbounded above, `start..`.
        type: object
        properties:
          start:
            type: integer
            format: int16
          type:
            type: string
            enum:
            - range_from
        required:
        - start
        - type
    BinRangeint32:
      description: 'A type storing a range over `T`.


        This type supports ranges similar to the `RangeTo`, `Range` and `RangeFrom` types in the standard library. Those cover `(..end)`, `(start..end)`, and `(start..)` respectively.'
      oneOf:
      - description: A range unbounded below and exclusively above, `..end`.
        type: object
        properties:
          end:
            type: integer
            format: int32
          type:
            type: string
            enum:
            - range_to
        required:
        - end
        - type
      - description: A range bounded inclusively below and exclusively above, `start..end`.
        type: object
        properties:
          end:
            type: integer
            format: int32
          start:
            type: integer
            format: int32
          type:
            type: string
            enum:
            - range
        required:
        - end
        - start
        - type
      - description: A range bounded inclusively below and unbounded above, `start..`.
        type: object
        properties:
          start:
            type: integer
            format: int32
          type:
            type: string
            enum:
            - range_from
        required:
        - start
        - type
    Binint64:
      description: Type storing bin edges and a count of samples within it.
      type: object
      properties:
        count:
          description: The total count of samples in this bin.
          type: integer
          format: uint64
          minimum: 0
        range:
          description: The range of the support covered by this bin.
          allOf:
          - $ref: '#/components/schemas/BinRangeint64'
      required:
      - count
      - range
    TimeseriesSchema:
      description: 'The schema for a timeseries.


        This includes the name of the timeseries, as well as the datum type of its metric and the schema for each field.'
      type: object
      properties:
        authz_scope:
          $ref: '#/components/schemas/AuthzScope'
        created:
          type: string
          format: date-time
        datum_type:
          $ref: '#/components/schemas/DatumType'
        description:
          $ref: '#/components/schemas/TimeseriesDescription'
        field_schema:
          type: array
          items:
            $ref: '#/components/schemas/FieldSchema'
          uniqueItems: true
        timeseries_name:
          $ref: '#/components/schemas/TimeseriesName'
        units:
          $ref: '#/components/schemas/Units'
        version:
          type: integer
          format: uint8
          minimum: 1
      required:
      - authz_scope
      - created
      - datum_type
      - description
      - field_schema
      - timeseries_name
      - units
      - version
    BinRangeuint8:
      description: 'A type storing a range over `T`.


        This type supports ranges similar to the `RangeTo`, `Range` and `RangeFrom` types in the standard library. Those cover `(..end)`, `(start..end)`, and `(start..)` respectively.'
      oneOf:
      - description: A range unbounded below and exclusively above, `..end`.
        type: object
        properties:
          end:
            type: integer
            format: uint8
            minimum: 0
          type:
            type: string
            enum:
            - range_to
        required:
        - end
        - type
      - description: A range bounded inclusively below and exclusively above, `start..end`.
        type: object
        properties:
          end:
            type: integer
            format: uint8
            minimum: 0
          start:
            type: integer
            format: uint8
            minimum: 0
          type:
            type: string
            enum:
            - range
        required:
        - end
        - start
        - type
      - description: A range bounded inclusively below and unbounded above, `start..`.
        type: object
        properties:
          start:
            type: integer
            format: uint8
            minimum: 0
          type:
            type: string
            enum:
            - range_from
        required:
        - start
        - type
    Cumulativefloat:
      description: A cumulative or counter data type.
      type: object
      properties:
        start_time:
          type: string
          format: date-time
        value:
          type: number
          format: float
      required:
      - start_time
      - value
    Binint8:
      description: Type storing bin edges and a count of samples within it.
      type: object
      properties:
        count:
          description: The total count of samples in this bin.
          type: integer
          format: uint64
          minimum: 0
        range:
          description: The range of the support covered by this bin.
          allOf:
          - $ref: '#/components/schemas/BinRangeint8'
      required:
      - count
      - range
    BinRangefloat:
      description: 'A type storing a range over `T`.


        This type supports ranges similar to the `RangeTo`, `Range` and `RangeFrom` types in the standard library. Those cover `(..end)`, `(start..end)`, and `(start..)` respectively.'
      oneOf:
      - description: A range unbounded below and exclusively above, `..end`.
        type: object
        properties:
          end:
            type: number
            format: float
          type:
            type: string
            enum:
            - range_to
        required:
        - end
        - type
      - description: A range bounded inclusively below and exclusively above, `start..end`.
        type: object
        properties:
          end:
            type: number
            format: float
          start:
            type: number
            format: float
          type:
            type: string
            enum:
            - range
        required:
        - end
        - start
        - type
      - description: A range bounded inclusively below and unbounded above, `start..`.
        type: object
        properties:
          start:
            type: number
            format: float
          type:
            type: string
            enum:
            - range_from
        required:
        - start
        - type
    Binint16:
      description: Type storing bin edges and a count of samples within it.
      type: object
      properties:
        count:
          description: The total count of samples in this bin.
          type: integer
          format: uint64
          minimum: 0
        range:
          description: The range of the support covered by this bin.
          allOf:
          - $ref: '#/components/schemas/BinRangeint16'
      required:
      - count
      - range
    Binuint64:
      description: Type storing bin edges and a count of samples within it.
      type: object
      properties:
        count:
          description: The total count of samples in this bin.
          type: integer
          format: uint64
          minimum: 0
        range:
          description: The range of the support covered by this bin.
          allOf:
          - $ref: '#/components/schemas/BinRangeuint64'
      required:
      - count
      - range
    OxqlTable:
      description: 'A table represents one or more timeseries with the same schema.


        A table is the result of an OxQL query. It contains a name, usually the name of the timeseries schema from which the data is derived, and any number of timeseries, which contain the actual data.'
      type: object
      properties:
        name:
          description: The name of the table.
          type: string
        timeseries:
          description: The set of timeseries in the table, ordered by key.
          type: array
          items:
            $ref: '#/components/schemas/Timeseries'
      required:
      - name
      - timeseries
    FieldSource:
      description: The source from which a field is derived, the target or metric.
      type: string
      enum:
      - target
      - metric
    Cumulativeuint64:
      description: A cumulative or counter data type.
      type: object
      properties:
        start_time:
          type: string
          format: date-time
        value:
          type: integer
          format: uint64
          minimum: 0
      required:
      - start_time
      - value
    Timeseries:
      description: 'A timeseries contains a timestamped set of values from one source.


        This includes the typed key-value pairs that uniquely identify it, and the set of timestamps and data values from it.'
      type: object
      properties:
        fields:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FieldValue'
        points:
          $ref: '#/components/schemas/Points'
      required:
      - fields
      - points
    BinRangedouble:
      description: 'A type storing a range over `T`.


        This type supports ranges similar to the `RangeTo`, `Range` and `RangeFrom` types in the standard library. Those cover `(..end)`, `(start..end)`, and `(start..)` respectively.'
      oneOf:
      - description: A range unbounded below and exclusively above, `..end`.
        type: object
        properties:
          end:
            type: number
            format: double
          type:
            type: string
            enum:
            - range_to
        required:
        - end
        - type
      - description: A range bounded inclusively below and exclusively above, `start..end`.
        type: object
        properties:
          end:
            type: number
            format: double
          start:
            type: number
            format: double
          type:
            type: string
            enum:
            - range
        required:
        - end
        - start
        - type
      - description: A range bounded inclusively below and unbounded above, `start..`.
        type: object
        properties:
          start:
            type: number
            format: double
          type:
            type: string
            enum:
            - range_from
        required:
        - start
        - type
    Cumulativeint64:
      description: A cumulative or counter data type.
      type: object
      properties:
        start_time:
          type: string
          format: date-time
        value:
          type: integer
          format: int64
      required:
      - start_time
      - value
    Quantile:
      description: 'Structure for estimating the p-quantile of a population.


        This is based on the P² algorithm for estimating quantiles using constant space.


        The algorithm consists of maintaining five markers: the minimum, the p/2-, p-, and (1 + p)/2 quantiles, and the maximum.'
      type: object
      properties:
        desired_marker_positions:
          description: The desired marker positions.
          type: array
          items:
            type: number
            format: double
          minItems: 5
          maxItems: 5
        marker_heights:
          description: The heights of the markers.
          type: array
          items:
            type: number
            format: double
          minItems: 5
          maxItems: 5
        marker_positions:
          description: 'The positions of the markers.


            We track sample size in the 5th position, as useful observations won''t start until we''ve filled the heights at the 6th sample anyway This does deviate from the paper, but it''s a more useful representation that works according to the paper''s algorithm.'
          type: array
          items:
            type: integer
            format: uint64
            minimum: 0
          minItems: 5
          maxItems: 5
        p:
          description: The p value for the quantile.
          type: number
          format: double
      required:
      - desired_marker_positions
      - marker_heights
      - marker_positions
      - p
    Binuint32:
      description: Type storing bin edges and a count of samples within it.
      type: object
      properties:
        count:
          description: The total count of samples in this bin.
          type: integer
          format: uint64
          minimum: 0
        range:
          description: The range of the support covered by this bin.
          allOf:
          - $ref: '#/components/schemas/BinRangeuint32'
      required:
      - count
      - range
    TimeseriesQuery:
      description: A timeseries query string, written in the Oximeter query language.
      type: object
      properties:
        query:
          description: A timeseries query string, written in the Oximeter query language.
          type: string
      required:
      - query
    Histogramuint32:
      description: 'Histogram metric


        A histogram maintains the count of any number of samples, over a set of bins. Bins are specified on construction via their _left_ edges, inclusive. There can''t be any "gaps" in the bins, and an additional bin may be added to the left, right, or both so that the bins extend to the entire range of the support.


        Note that any gaps, unsorted bins, or non-finite values will result in an error.'
      type: object
      properties:
        bins:
          description: The bins of the histogram.
          type: array
          items:
            $ref: '#/components/schemas/Binuint32'
        max:
          description: The maximum value of all samples in the histogram.
          type: integer
          format: uint32
          minimum: 0
        min:
          description: The minimum value of all samples in the histogram.
          type: integer
          format: uint32
          minimum: 0
        n_samples:
          description: The total number of samples in the histogram.
          type: integer
          format: uint64
          minimum: 0
        p50:
          description: p50 Quantile
          allOf:
          - $ref: '#/components/schemas/Quantile'
        p90:
          description: p95 Quantile
          allOf:
          - $ref: '#/components/schemas/Quantile'
        p99:
          description: p99 Quantile
          allOf:
          - $ref: '#/components/schemas/Quantile'
        squared_mean:
          description: 'M2 for Welford''s algorithm for variance calculation.


            Read about [Welford''s algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford''s_online_algorithm) for more information on the algorithm.'
          type: number
          format: double
        start_time:
          description: The start time of the histogram.
          type: string
          format: date-time
        sum_of_samples:
          description: The sum of all samples in the histogram.
          type: integer
          format: int64
      required:
      - bins
      - max
      - min
      - n_samples
      - p50
      - p90
      - p99
      - squared_mean
      - start_time
      - sum_of_samples
    BinRangeint8:
      description: 'A type storing a range over `T`.


        This type supports ranges similar to the `RangeTo`, `Range` and `RangeFrom` types in the standard library. Those cover `(..end)`, `(start..end)`, and `(start..)` respectively.'
      oneOf:
      - description: A range unbounded below and exclusively above, `..end`.
        type: object
        properties:
          end:
            type: integer
            format: int8
          type:
            type: string
            enum:
            - range_to
        required:
        - end
        - type
      - description: A range bounded inclusively below and exclusively above, `start..end`.
        type: object
        properties:
          end:
            type: integer
            format: int8
          start:
            type: integer
            format: int8
          type:
            type: string
            enum:
            - range
        required:
        - end
        - start
        - type
      - description: A range bounded inclusively below and unbounded above, `start..`.
        type: object
        properties:
          start:
            type: integer
            format: int8
          type:
            type: string
            enum:
            - range_from
        required:
        - start
        - type
    FieldSchema:
      description: The name and type information for a field of a timeseries schema.
      type: object
      properties:
        description:
          type: string
        field_type:
          $ref: '#/components/schemas/FieldType'
        name:
          type: string
        source:
          $ref: '#/components/schemas/FieldSource'
      required:
      - description
      - field_type
      - name
      - source
    Points:
      description: Timepoints and values for one timeseries.
      type: object
      properties:
        start_times:
          type:
          - array
          - 'null'
          items:
            type: string
            format: date-time
        timestamps:
          type: array
          items:
            type: string
            format: date-time
        values:
          type: array
          items:
            $ref: '#/components/schemas/Values'
      required:
      - timestamps
      - values
    AuthzScope:
      description: 'Authorization scope for a timeseries.


        This describes the level at which a user must be authorized to read data from a timeseries. For example, fleet-scoping means the data is only visible to an operator or fleet reader. Project-scoped, on the other hand, indicates that a user will see data limited to the projects on which they have read permissions.'
      oneOf:
      - description: Timeseries data is limited to fleet readers.
        type: string
        enum:
        - fleet
      - description: Timeseries data is limited to the authorized silo for a user.
        type: string
        enum:
        - silo
      - description: Timeseries data is limited to the authorized projects for a user.
        type: string
        enum:
        - project
      - description: The timeseries is viewable to all without limitation.
        type: string
        enum:
        - viewable_to_all
    MissingDatum:
      type: object
      properties:
        datum_type:
          $ref: '#/components/schemas/DatumType'
        start_time:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - datum_type
    Distributionint64:
      description: 'A distribution is a sequence of bins and counts in those bins, and some statistical information tracked to compute the mean, standard deviation, and quantile estimates.


        Min, max, and the p-* quantiles are treated as optional due to the possibility of distribution operations, like subtraction.'
      type: object
      properties:
        bins:
          type: array
          items:
            type: integer
            format: int64
        counts:
          type: array
          items:
            type: integer
            format: uint64
            minimum: 0
        max:
          type:
          - integer
          - 'null'
          format: int64
        min:
          type:
          - integer
          - 'null'
          format: int64
        p50:
          type:
          - number
          - 'null'
          format: double
        p90:
          type:
          - number
          - 'null'
          format: double
        p99:
          type:
          - number
          - 'null'
          format: double
        squared_mean:
          type: number
          format: double
        sum_of_samples:
          type: integer
          format: int64
      required:
      - bins
      - counts
      - squared_mean
      - sum_of_samples
    Histogramint32:
      description: 'Histogram metric


        A histogram maintains the count of any number of samples, over a set of bins. Bins are specified on construction via their _left_ edges, inclusive. There can''t be any "gaps" in the bins, and an additional bin may be added to the left, right, or both so that the bins extend to the entire range of the support.


        Note that any gaps, unsorted bins, or non-finite values will result in an error.'
      type: object
      properties:
        bins:
          description: The bins of the histogram.
          type: array
          items:
            $ref: '#/components/schemas/Binint32'
        max:
          description: The maximum value of all samples in the histogram.
          type: integer
          format: int32
        min:
          description: The minimum value of all samples in the histogram.
          type: integer
          format: int32
        n_samples:
          description: The total number of samples in the histogram.
          type: integer
          format: uint64
          minimum: 0
        p50:
          description: p50 Quantile
          allOf:
          - $ref: '#/components/schemas/Quantile'
        p90:
          description: p95 Quantile
          allOf:
          - $ref: '#/components/schemas/Quantile'
        p99:
          description: p99 Quantile
          allOf:
          - $ref: '#/components/schemas/Quantile'
        squared_mean:
          description: 'M2 for Welford''s algorithm for variance calculation.


            Read about [Welford''s algorithm](https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford''s_online_algorithm) for more information on the algorithm.'
          type: number
          format: double
        start_time:
          description: The start time of the histogram.
          type: string
          format: date-time
        sum_of_samples:
          description: The sum of all samples in the histogram.
          type: integer
          format: int64
      required:
      - bins
      - max
      - min
      - n_samples
      - p50
      - p90
      - p99
      - squared_mean
      - start_time
      - sum_of_samples
    Error:
      description: Error information from a response.
      type: object
      properties:
        error_code:
          type: string
        message:
          type: string
        request_id:
          type: string
      required:
      - message
      - request_id
    DatumType:
      description: The type of an individual datum of a metric.
      type: string
      enum:
      - bool
      - i8
      - u8
      - i16
      - u16
      - i32
      - u32
      - i64
      - u64
      - f32
      - f64
      - string
      - bytes
      - cumulative_i64
      - cumulative_u64
      - cumulative_f32
      - cumulative_f64
      - histogram_i8
      - histogram_u8
      - histogram_i16
      - histogram_u16
      - histogram_i32
      - histogram_u32
      - histogram_i64
      - histogram_u64
      - histogram_f32
      - histogram_f64
    FieldValue:
      description: The `FieldValue` contains the value of a target or metric field.
      oneOf:
      - type: object
        properties:
          type:
            type: string
            enum:
            - string
          value:
            type: string
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - i8
          value:
            type: integer
            format: int8
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - u8
          value:
            type: integer
            format: uint8
            minimum: 0
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - i16
          value:
            type: integer
            format: int16
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - u16
          value:
            type: integer
            format: uint16
            minimum: 0
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - i32
          value:
            type: integer
            format: int32
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - u32
          value:
            type: integer
            format: uint32
            minimum: 0
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - i64
          value:
            type: integer
            format: int64
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - u64
          value:
            type: integer
            format: uint64
            minimum: 0
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - ip_addr
          value:
            type: string
            format: ip
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - uuid
          value:
            type: string
            format: uuid
        required:
        - type
        - value
      - type: object
        properties:
          type:
            type: string
            enum:
            - bool
          value:
            type: boolean
        required:
        - type
        - value
    Histogramuint64:
      description: 'Histogram metric


        A histogram maintains the count of any number of samples, over a set of bins. Bins are specified on construction via their _left_ edges, inclusive. There can''t be any "gaps" in the bins, and an additional bin may be added to the left, right, or both so that the bins extend to the entire range of the support.


        Note that any gaps, unsorted bins, or non

# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/oxide-computer/refs/heads/main/openapi/oxide-computer-system-metrics-api-openapi.yml