> ## Documentation Index
> Fetch the complete documentation index at: https://s2.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Get basin-level S2 metrics for storage, operations, and throughput.
# Basin-level metrics.
Review metric sets, parameters, scopes, and response types.
### Metric sets
#### `storage`
`gauge` of cumulative stored bytes, per hour, aggregated across all streams within the basin.
Requires a `start` and `end` timestamp.
#### `append-ops`
Returns `accumulation` of append operations aggregated across all streams within the basin, grouped by storage class.
An append operation is defined as one minute of appends to a single stream, using a single TCP connection.
For instance, 10 unary appends to stream `X`, each initializing a new connection, would be 10 append operations. 10 unary or streaming session appends to stream `X`, on a single TCP connection, within a single minute, would be 1 append operation.
Requires a `start` and `end` timestamp. Accepts an optional `interval` parameter for `minute` / `hour` / `day` aggregations.
#### `read-ops`
Returns two `accumulation` metrics of read operations, aggregated across all streams within the basin: one for `unary` reads, and another for `streaming` reads.
A streaming read operation is defined as up to one minute of a streaming read response, from a single stream, using a single TCP connection.
A unary read operation is a single read request that does not return a streaming body.
Requires a `start` and `end` timestamp. Accepts an optional `interval` parameter for `minute` / `hour` / `day` aggregations.
#### `read-throughput`
`accumulation` of read throughput in bytes, aggregated across all streams within the basin.
Requires a `start` and `end` timestamp. Accepts an optional `interval` parameter for `minute` / `hour` / `day` aggregations.
This metric set does not currently separate egress traffic by client origin, which will be a [dimension for billing](https://s2.dev/pricing).
#### `append-throughput`
Returns two `accumulation` metrics of appended throughput in bytes, aggregated across all streams within the basin: one for appends against `express` storage class streams, and another for appends against `standard` storage class streams.
Requires a `start` and `end` timestamp. Accepts an optional `interval` parameter for `minute` / `hour` / `day` aggregations.
#### `basin-ops`
Set of `accumulation` metrics, one per basin operation. Each basin-level request is a single operation, and this endpoint will return as many timeseries as there are distinct basin operations with non-zero values within the specified period.
Requires a `start` and `end` timestamp. Accepts an optional `interval` parameter for `minute` / `hour` / `day` aggregations.
## OpenAPI
````yaml get /metrics/{basin}
openapi: 3.1.0
info:
title: S2, the durable streams 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://aws.s2.dev/v1
security:
- access_token: []
tags:
- name: metrics
description: Usage metrics and data.
- name: basins
description: Manage basins
- name: access-tokens
description: Manage access tokens
- name: locations
description: Manage locations
- name: streams
description: Manage streams
- name: records
description: Manage records
paths:
/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'
components:
schemas:
BasinMetricSet:
type: string
enum:
- storage
- append-ops
- read-ops
- read-throughput
- append-throughput
- basin-ops
TimeseriesInterval:
type: string
enum:
- minute
- hour
- day
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.
ErrorInfo:
type: object
required:
- code
- message
properties:
code:
type: string
message:
type: string
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.
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`.
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.
MetricUnit:
type: string
enum:
- bytes
- operations
securitySchemes:
access_token:
type: http
scheme: bearer
description: >-
Bearer authentication header of the form `Bearer `, where
`` is your access token.
````