ObjectStackObjectStack

Metrics

Metrics protocol schemas

Metrics Protocol - Performance and Operational Metrics

Comprehensive metrics collection and monitoring:

  • Counter, Gauge, Histogram, Summary metric types
  • Time-series data collection
  • SLI/SLO definitions
  • Metric aggregation and export
  • Integration with monitoring systems (Prometheus, etc.)

Source: packages/spec/src/system/metrics.zod.ts

TypeScript Usage

import { HistogramBucketConfigSchema, MetricAggregationConfigSchema, MetricAggregationType, MetricDataPointSchema, MetricDefinitionSchema, MetricExportConfigSchema, MetricLabelsSchema, MetricType, MetricUnit, MetricsConfigSchema, ServiceLevelIndicatorSchema, ServiceLevelObjectiveSchema, TimeSeriesSchema, TimeSeriesDataPointSchema } from '@objectstack/spec/system';
import type { HistogramBucketConfig, MetricAggregationConfig, MetricAggregationType, MetricDataPoint, MetricDefinition, MetricExportConfig, MetricLabels, MetricType, MetricUnit, MetricsConfig, ServiceLevelIndicator, ServiceLevelObjective, TimeSeries, TimeSeriesDataPoint } from '@objectstack/spec/system';

// Validate data
const result = HistogramBucketConfigSchema.parse(data);

HistogramBucketConfig

Histogram bucket configuration

Properties

PropertyTypeRequiredDescription
typeEnum<'linear' | 'exponential' | 'explicit'>✅Bucket type
linear{ start: number; width: number; count: integer }optional
exponential{ start: number; factor: number; count: integer }optional
explicit{ boundaries: number[] }optional

Nested Shape: HistogramBucketConfig.linear

PropertyTypeRequiredDescription
startnumber✅Start value
widthnumber✅Bucket width
countinteger✅Number of buckets

Nested Shape: HistogramBucketConfig.exponential

PropertyTypeRequiredDescription
startnumber✅Start value
factornumber✅Growth factor
countinteger✅Number of buckets

Nested Shape: HistogramBucketConfig.explicit

PropertyTypeRequiredDescription
boundariesnumber[]✅Bucket boundaries

MetricAggregationConfig

Metric aggregation configuration

Properties

PropertyTypeRequiredDescription
typeEnum<'sum' | 'avg' | 'min' | 'max' | 'count' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | 'p999' | 'rate' | 'stddev'>✅Aggregation type
window{ size: integer; sliding: boolean; slideInterval?: integer }optional
groupBystring[]optionalGroup by label names
filtersRecord<string, any>optionalFilter criteria

Nested Shape: MetricAggregationConfig.window

PropertyTypeRequiredDescription
sizeinteger✅Window size in seconds
slidingbooleanoptional (default: false)
slideIntervalintegeroptional

MetricAggregationType

Metric aggregation type

Allowed Values

  • sum
  • avg
  • min
  • max
  • count
  • p50
  • p75
  • p90
  • p95
  • p99
  • p999
  • rate
  • stddev

MetricDataPoint

Metric data point

Properties

PropertyTypeRequiredDescription
namestring✅Metric name
typeEnum<'counter' | 'gauge' | 'histogram' | 'summary'>✅Metric type
timestampstring✅Observation timestamp
valuenumberoptionalMetric value
labelsRecord<string, string>optionalMetric labels
histogram{ count: integer; sum: number; buckets: object[] }optional
summary{ count: integer; sum: number; quantiles: object[] }optional

Nested Shape: MetricDataPoint.histogram

PropertyTypeRequiredDescription
countinteger✅Total count
sumnumber✅Sum of all values
buckets{ upperBound: number; count: integer }[]✅Histogram buckets

Nested Shape: MetricDataPoint.summary

PropertyTypeRequiredDescription
countinteger✅Total count
sumnumber✅Sum of all values
quantiles{ quantile: number; value: number }[]✅Summary quantiles

MetricDefinition

Metric definition

Properties

PropertyTypeRequiredDescription
namestring✅Metric name (snake_case)
labelstringoptionalDisplay label
typeEnum<'counter' | 'gauge' | 'histogram' | 'summary'>✅Metric type
unitEnum<'nanoseconds' | 'microseconds' | 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'bytes' | 'kilobytes' | 'megabytes' | 'gigabytes' | 'terabytes' | … +8 more>optionalMetric unit
descriptionstringoptionalMetric description
labelNamesstring[]optional (default: [])Label names
histogram{ type: Enum<'linear' | 'exponential' | 'explicit'>; linear?: object; exponential?: object; explicit?: object }optionalHistogram bucket configuration
summary{ quantiles: number[]; maxAge: integer; ageBuckets: integer }optional
enabledbooleanoptional (default: true)

Allowed Values: MetricDefinition.unit

  • nanoseconds
  • microseconds
  • milliseconds
  • seconds
  • minutes
  • hours
  • days
  • bytes
  • kilobytes
  • megabytes
  • gigabytes
  • terabytes
  • requests_per_second
  • events_per_second
  • bytes_per_second
  • percent
  • ratio
  • count
  • operations
  • custom

Nested Shape: MetricDefinition.histogram

PropertyTypeRequiredDescription
typeEnum<'linear' | 'exponential' | 'explicit'>✅Bucket type
linear{ start: number; width: number; count: integer }optional
exponential{ start: number; factor: number; count: integer }optional
explicit{ boundaries: number[] }optional

MetricExportConfig

Metric export configuration

Properties

PropertyTypeRequiredDescription
typeEnum<'prometheus' | 'openmetrics' | 'graphite' | 'statsd' | 'influxdb' | 'datadog' | 'cloudwatch' | 'stackdriver' | 'azure_monitor' | 'http' | 'custom'>✅Export type
endpointstringoptionalExport endpoint
intervalintegeroptional (default: 60)
batch{ enabled: boolean; size: integer }optional
auth{ type: Enum<'none' | 'basic' | 'bearer' | 'api_key'>; username?: string; password?: string; token?: string; … }optional
configRecord<string, any>optionalAdditional configuration

Nested Shape: MetricExportConfig.auth

PropertyTypeRequiredDescription
typeEnum<'none' | 'basic' | 'bearer' | 'api_key'>✅Auth type
usernamestringoptional
passwordstringoptional
tokenstringoptional
apiKeystringoptional

MetricLabels

Metric labels

Type: Record<string, string>

MetricType

Metric type

Allowed Values

  • counter
  • gauge
  • histogram
  • summary

MetricUnit

Metric unit

Allowed Values

  • nanoseconds
  • microseconds
  • milliseconds
  • seconds
  • minutes
  • hours
  • days
  • bytes
  • kilobytes
  • megabytes
  • gigabytes
  • terabytes
  • requests_per_second
  • events_per_second
  • bytes_per_second
  • percent
  • ratio
  • count
  • operations
  • custom

MetricsConfig

Metrics configuration

Properties

PropertyTypeRequiredDescription
namestring✅Configuration name (snake_case, max 64 chars)
labelstring✅Display label
enabledbooleanoptional (default: true)
metrics{ name: string; label?: string; type: Enum<'counter' | 'gauge' | 'histogram' | 'summary'>; unit?: Enum<'nanoseconds' | 'microseconds' | 'milliseconds' | 'seconds' | 'minutes' | …>; … }[]optional (default: [])
defaultLabelsRecord<string, string>optional (default: {})Metric labels
aggregations{ type: Enum<'sum' | 'avg' | 'min' | 'max' | 'count' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | …>; window?: object; groupBy?: string[]; filters?: Record<string, any> }[]optional (default: [])
slis{ name: string; label: string; description?: string; metric: string; … }[]optional
slos{ name: string; label: string; description?: string; sli: string; … }[]optional (default: [])
exports{ type: Enum<'prometheus' | 'openmetrics' | 'graphite' | 'statsd' | 'influxdb' | 'datadog' | …>; endpoint?: string; interval?: integer; batch?: object; … }[]optional (default: [])
collectionIntervalintegeroptional (default: 15)
retention{ period?: integer; downsampling?: object[] }optional
cardinalityLimits{ maxLabelCombinations?: integer; onLimitExceeded?: Enum<'drop' | 'sample' | 'alert'> }optional

Nested Shape: MetricsConfig.metrics[number]

Metric definition

PropertyTypeRequiredDescription
namestring✅Metric name (snake_case)
labelstringoptionalDisplay label
typeEnum<'counter' | 'gauge' | 'histogram' | 'summary'>✅Metric type
unitEnum<'nanoseconds' | 'microseconds' | 'milliseconds' | 'seconds' | 'minutes' | …>optionalMetric unit
descriptionstringoptionalMetric description
labelNamesstring[]optional (default: [])Label names
histogram{ type: Enum<'linear' | 'exponential' | 'explicit'>; linear?: object; exponential?: object; explicit?: object }optionalHistogram bucket configuration
summary{ quantiles?: number[]; maxAge?: integer; ageBuckets?: integer }optional
enabledbooleanoptional (default: true)

Nested Shape: MetricsConfig.aggregations[number]

Metric aggregation configuration

PropertyTypeRequiredDescription
typeEnum<'sum' | 'avg' | 'min' | 'max' | 'count' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99' | …>✅Aggregation type
window{ size: integer; sliding?: boolean; slideInterval?: integer }optional
groupBystring[]optionalGroup by label names
filtersRecord<string, any>optionalFilter criteria

Nested Shape: MetricsConfig.slis[number]

Service Level Indicator

PropertyTypeRequiredDescription
namestring✅SLI name (snake_case)
labelstring✅Display label
descriptionstringoptionalSLI description
metricstring✅Base metric name
typeEnum<'availability' | 'latency' | 'throughput' | 'error_rate' | 'saturation' | 'custom'>✅SLI type
successCriteria{ threshold: number; operator: Enum<'lt' | 'lte' | 'gt' | 'gte' | 'eq'>; percentile?: number } | string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }✅Success criteria — structured or CEL predicate
window{ size: integer; rolling?: boolean }✅Measurement window
enabledbooleanoptional (default: true)

Nested Shape: MetricsConfig.slos[number]

Service Level Objective

PropertyTypeRequiredDescription
namestring✅SLO name (snake_case)
labelstring✅Display label
descriptionstringoptionalSLO description
slistring✅SLI name
targetnumber✅Target percentage
period{ type: Enum<'rolling' | 'calendar'>; duration?: integer; calendar?: Enum<'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'> }✅Time period
errorBudget{ enabled?: boolean; alertThreshold?: number; burnRateWindows?: object[] }optional
alerts{ name: string; severity: Enum<'info' | 'warning' | 'critical'>; condition: object }[]optional (default: [])
enabledbooleanoptional (default: true)

Nested Shape: MetricsConfig.exports[number]

Metric export configuration

PropertyTypeRequiredDescription
typeEnum<'prometheus' | 'openmetrics' | 'graphite' | 'statsd' | 'influxdb' | 'datadog' | …>✅Export type
endpointstringoptionalExport endpoint
intervalintegeroptional (default: 60)
batch{ enabled?: boolean; size?: integer }optional
auth{ type: Enum<'none' | 'basic' | 'bearer' | 'api_key'>; username?: string; password?: string; token?: string; … }optional
configRecord<string, any>optionalAdditional configuration

ServiceLevelIndicator

Service Level Indicator

Properties

PropertyTypeRequiredDescription
namestring✅SLI name (snake_case)
labelstring✅Display label
descriptionstringoptionalSLI description
metricstring✅Base metric name
typeEnum<'availability' | 'latency' | 'throughput' | 'error_rate' | 'saturation' | 'custom'>✅SLI type
successCriteria{ threshold: number; operator: Enum<'lt' | 'lte' | 'gt' | 'gte' | 'eq'>; percentile?: number } | string | { dialect: Enum<'cel' | 'cron' | 'template'>; source?: string; ast?: any; meta?: object }✅Success criteria — structured or CEL predicate
window{ size: integer; rolling?: boolean }✅Measurement window
enabledbooleanoptional (default: true)

Nested Shape: ServiceLevelIndicator.successCriteria[option 1]

PropertyTypeRequiredDescription
thresholdnumber✅Threshold value
operatorEnum<'lt' | 'lte' | 'gt' | 'gte' | 'eq'>✅Comparison operator
percentilenumberoptionalPercentile (0-1)

Nested Shape: ServiceLevelIndicator.window

PropertyTypeRequiredDescription
sizeinteger✅Window size in seconds
rollingbooleanoptional (default: true)

ServiceLevelObjective

Service Level Objective

Properties

PropertyTypeRequiredDescription
namestring✅SLO name (snake_case)
labelstring✅Display label
descriptionstringoptionalSLO description
slistring✅SLI name
targetnumber✅Target percentage
period{ type: Enum<'rolling' | 'calendar'>; duration?: integer; calendar?: Enum<'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'> }✅Time period
errorBudget{ enabled: boolean; alertThreshold: number; burnRateWindows?: object[] }optional
alerts{ name: string; severity: Enum<'info' | 'warning' | 'critical'>; condition: object }[]optional (default: [])
enabledbooleanoptional (default: true)

Nested Shape: ServiceLevelObjective.period

PropertyTypeRequiredDescription
typeEnum<'rolling' | 'calendar'>✅Period type
durationintegeroptionalDuration in seconds
calendarEnum<'daily' | 'weekly' | 'monthly' | 'quarterly' | 'yearly'>optional

Nested Shape: ServiceLevelObjective.alerts[number]

PropertyTypeRequiredDescription
namestring✅Alert name
severityEnum<'info' | 'warning' | 'critical'>✅Alert severity
condition{ type: Enum<'slo_breach' | 'error_budget' | 'burn_rate'>; threshold?: number }✅Alert condition

TimeSeries

Time series

Properties

PropertyTypeRequiredDescription
namestring✅Series name
labelsRecord<string, string>optionalSeries labels
dataPoints{ timestamp: string; value: number; labels?: Record<string, string> }[]✅Data points
startTimestringoptionalStart time
endTimestringoptionalEnd time

Nested Shape: TimeSeries.dataPoints[number]

Time series data point

PropertyTypeRequiredDescription
timestampstring✅Timestamp
valuenumber✅Value
labelsRecord<string, string>optionalLabels

TimeSeriesDataPoint

Time series data point

Properties

PropertyTypeRequiredDescription
timestampstring✅Timestamp
valuenumber✅Value
labelsRecord<string, string>optionalLabels

On this page

TypeScript UsageHistogramBucketConfigPropertiesNested Shape: HistogramBucketConfig.linearNested Shape: HistogramBucketConfig.exponentialNested Shape: HistogramBucketConfig.explicitMetricAggregationConfigPropertiesNested Shape: MetricAggregationConfig.windowMetricAggregationTypeAllowed ValuesMetricDataPointPropertiesNested Shape: MetricDataPoint.histogramNested Shape: MetricDataPoint.summaryMetricDefinitionPropertiesAllowed Values: MetricDefinition.unitNested Shape: MetricDefinition.histogramMetricExportConfigPropertiesNested Shape: MetricExportConfig.authMetricLabelsMetricTypeAllowed ValuesMetricUnitAllowed ValuesMetricsConfigPropertiesNested Shape: MetricsConfig.metrics[number]Nested Shape: MetricsConfig.aggregations[number]Nested Shape: MetricsConfig.slis[number]Nested Shape: MetricsConfig.slos[number]Nested Shape: MetricsConfig.exports[number]ServiceLevelIndicatorPropertiesNested Shape: ServiceLevelIndicator.successCriteria[option 1]Nested Shape: ServiceLevelIndicator.windowServiceLevelObjectivePropertiesNested Shape: ServiceLevelObjective.periodNested Shape: ServiceLevelObjective.alerts[number]TimeSeriesPropertiesNested Shape: TimeSeries.dataPoints[number]TimeSeriesDataPointProperties