OpenAPI Specification
openapi: 3.1.0
info:
title: S2, the durable streams access-tokens metrics API
description: Streams as a cloud storage primitive.
termsOfService: https://s2.dev/terms
contact:
email: support@s2.dev
license:
name: MIT
version: 1.0.0
servers:
- url: https://a.s2.dev/v1
security:
- access_token: []
tags:
- name: metrics
description: Usage metrics and data.
paths:
/metrics:
get:
tags:
- metrics
summary: Account-level metrics.
operationId: account_metrics
parameters:
- name: set
in: query
description: Metric set to return.
required: true
schema:
$ref: '#/components/schemas/AccountMetricSet'
- name: start
in: query
description: Start timestamp as Unix epoch seconds, if applicable for the metric set.
required: false
schema:
type: integer
format: int32
minimum: 0
- name: end
in: query
description: End timestamp as Unix epoch seconds, if applicable for the metric set.
required: false
schema:
type: integer
format: int32
minimum: 0
- name: interval
in: query
description: Interval to aggregate over for timeseries metric sets.
required: false
schema:
$ref: '#/components/schemas/TimeseriesInterval'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSetResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
'408':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
/metrics/{basin}:
get:
tags:
- metrics
summary: Basin-level metrics.
operationId: basin_metrics
parameters:
- name: set
in: query
description: Metric set to return.
required: true
schema:
$ref: '#/components/schemas/BasinMetricSet'
- name: start
in: query
description: Start timestamp as Unix epoch seconds, if applicable for the metric set.
required: false
schema:
type: integer
format: int32
minimum: 0
- name: end
in: query
description: End timestamp as Unix epoch seconds, if applicable for the metric set.
required: false
schema:
type: integer
format: int32
minimum: 0
- name: interval
in: query
description: Interval to aggregate over for timeseries metric sets.
required: false
schema:
$ref: '#/components/schemas/TimeseriesInterval'
- name: basin
in: path
description: Basin name.
required: true
schema:
$ref: '#/components/schemas/BasinNameStr'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSetResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
'408':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
/metrics/{basin}/{stream}:
get:
tags:
- metrics
summary: Stream-level metrics.
operationId: stream_metrics
parameters:
- name: set
in: query
description: Metric set to return.
required: true
schema:
$ref: '#/components/schemas/StreamMetricSet'
- name: start
in: query
description: Start timestamp as Unix epoch seconds, if applicable for the metric set.
required: false
schema:
type: integer
format: int32
minimum: 0
- name: end
in: query
description: End timestamp as Unix epoch seconds, if applicable for metric set.
required: false
schema:
type: integer
format: int32
minimum: 0
- name: interval
in: query
description: Interval to aggregate over for timeseries metric sets.
required: false
schema:
$ref: '#/components/schemas/TimeseriesInterval'
- name: basin
in: path
description: Basin name.
required: true
schema:
$ref: '#/components/schemas/BasinNameStr'
- name: stream
in: path
description: Stream name.
required: true
schema:
$ref: '#/components/schemas/StreamNameStr'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/MetricSetResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
'408':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
components:
schemas:
Metric:
oneOf:
- type: object
description: Single named value.
required:
- scalar
properties:
scalar:
$ref: '#/components/schemas/ScalarMetric'
description: Single named value.
- type: object
description: Named series of `(timestamp, value)` points representing an accumulation over a specified interval.
required:
- accumulation
properties:
accumulation:
$ref: '#/components/schemas/AccumulationMetric'
description: Named series of `(timestamp, value)` points representing an accumulation over a specified interval.
- type: object
description: Named series of `(timestamp, value)` points each representing an instantaneous value.
required:
- gauge
properties:
gauge:
$ref: '#/components/schemas/GaugeMetric'
description: Named series of `(timestamp, value)` points each representing an instantaneous value.
- type: object
description: Set of string labels.
required:
- label
properties:
label:
$ref: '#/components/schemas/LabelMetric'
description: Set of string labels.
MetricUnit:
type: string
enum:
- bytes
- operations
ScalarMetric:
type: object
required:
- name
- unit
- value
properties:
name:
type: string
description: Metric name.
unit:
$ref: '#/components/schemas/MetricUnit'
description: Unit of the metric.
value:
type: number
format: double
description: Metric value.
AccumulationMetric:
type: object
required:
- name
- unit
- interval
- values
properties:
interval:
$ref: '#/components/schemas/TimeseriesInterval'
description: The interval at which data points are accumulated.
name:
type: string
description: Timeseries name.
unit:
$ref: '#/components/schemas/MetricUnit'
description: Unit of the metric.
values:
type: array
items:
type: array
items: false
prefixItems:
- type: integer
format: int32
minimum: 0
- type: number
format: double
description: 'Timeseries values.
Each element is a tuple of a timestamp in Unix epoch seconds and a data point.
The data point represents the accumulated value for the time period starting at the timestamp, spanning one `interval`.'
StreamMetricSet:
type: string
enum:
- storage
BasinMetricSet:
type: string
enum:
- storage
- append-ops
- read-ops
- read-throughput
- append-throughput
- basin-ops
StreamNameStr:
type: string
maxLength: 512
minLength: 1
TimeseriesInterval:
type: string
enum:
- minute
- hour
- day
ErrorInfo:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
GaugeMetric:
type: object
required:
- name
- unit
- values
properties:
name:
type: string
description: Timeseries name.
unit:
$ref: '#/components/schemas/MetricUnit'
description: Unit of the metric.
values:
type: array
items:
type: array
items: false
prefixItems:
- type: integer
format: int32
minimum: 0
- type: number
format: double
description: 'Timeseries values.
Each element is a tuple of a timestamp in Unix epoch seconds and a data point.
The data point represents the value at the instant of the timestamp.'
LabelMetric:
type: object
required:
- name
- values
properties:
name:
type: string
description: Label name.
values:
type: array
items:
type: string
description: Label values.
AccountMetricSet:
type: string
enum:
- active-basins
- account-ops
BasinNameStr:
type: string
maxLength: 48
minLength: 8
MetricSetResponse:
type: object
required:
- values
properties:
values:
type: array
items:
$ref: '#/components/schemas/Metric'
description: Metrics comprising the set.
securitySchemes:
access_token:
type: http
scheme: bearer
description: Bearer authentication header of the form `Bearer <token>`, where `<token>` is your access token.