Metrics

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

Property	Type	Required	Description
type	`Enum<'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

MetricAggregationConfig

Metric aggregation configuration

Properties

Property	Type	Required	Description
type	`Enum<'sum' \| 'avg' \| 'min' \| 'max' \| 'count' \| 'p50' \| 'p75' \| 'p90' \| 'p95' \| 'p99' \| 'p999' \| 'rate' \| 'stddev'>`	✅	Aggregation type
window	`{ size: integer; sliding: boolean; slideInterval?: integer }`	optional
groupBy	`string[]`	optional	Group by label names
filters	`Record<string, any>`	optional	Filter criteria

MetricAggregationType

Metric aggregation type

Allowed Values

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

MetricDataPoint

Metric data point

Properties

Property	Type	Required	Description
name	`string`	✅	Metric name
type	`Enum<'counter' \| 'gauge' \| 'histogram' \| 'summary'>`	✅	Metric type
timestamp	`string`	✅	Observation timestamp
value	`number`	optional	Metric value
labels	`Record<string, string>`	optional	Metric labels
histogram	`{ count: integer; sum: number; buckets: object[] }`	optional
summary	`{ count: integer; sum: number; quantiles: object[] }`	optional

MetricDefinition

Metric definition

Properties

Property	Type	Required	Description
name	`string`	✅	Metric name (snake_case)
label	`string`	optional	Display label
type	`Enum<'counter' \| 'gauge' \| 'histogram' \| 'summary'>`	✅	Metric type
unit	`Enum<'nanoseconds' \| 'microseconds' \| 'milliseconds' \| 'seconds' \| 'minutes' \| 'hours' \| 'days' \| 'bytes' \| 'kilobytes' \| 'megabytes' \| 'gigabytes' \| 'terabytes' \| … +8 more>`	optional	Metric unit
description	`string`	optional	Metric description
labelNames	`string[]`	✅	Label names
histogram	`{ type: Enum<'linear' \| 'exponential' \| 'explicit'>; linear?: object; exponential?: object; explicit?: object }`	optional	Histogram bucket configuration
summary	`{ quantiles: number[]; maxAge: integer; ageBuckets: integer }`	optional
enabled	`boolean`	✅

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

MetricExportConfig

Metric export configuration

Properties

Property	Type	Required	Description
type	`Enum<'prometheus' \| 'openmetrics' \| 'graphite' \| 'statsd' \| 'influxdb' \| 'datadog' \| 'cloudwatch' \| 'stackdriver' \| 'azure_monitor' \| 'http' \| 'custom'>`	✅	Export type
endpoint	`string`	optional	Export endpoint
interval	`integer`	✅
batch	`{ enabled: boolean; size: integer }`	optional
auth	`{ type: Enum<'none' \| 'basic' \| 'bearer' \| 'api_key'>; username?: string; password?: string; token?: string; … }`	optional
config	`Record<string, any>`	optional	Additional configuration

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

Property	Type	Required	Description
name	`string`	✅	Configuration name (snake_case, max 64 chars)
label	`string`	✅	Display label
enabled	`boolean`	optional
metrics	`{ name: string; label?: string; type: Enum<'counter' \| 'gauge' \| 'histogram' \| 'summary'>; unit?: Enum<'nanoseconds' \| 'microseconds' \| 'milliseconds' \| 'seconds' \| 'minutes' \| … +15 more>; … }[]`	optional
defaultLabels	`Record<string, string>`	optional	Metric labels
aggregations	`{ type: Enum<'sum' \| 'avg' \| 'min' \| 'max' \| 'count' \| 'p50' \| 'p75' \| 'p90' \| 'p95' \| 'p99' \| … +3 more>; window?: object; groupBy?: string[]; filters?: Record<string, any> }[]`	optional
slis	`{ name: string; label: string; description?: string; metric: string; … }[]`	optional
slos	`{ name: string; label: string; description?: string; sli: string; … }[]`	optional
exports	`{ type: Enum<'prometheus' \| 'openmetrics' \| 'graphite' \| 'statsd' \| 'influxdb' \| 'datadog' \| … +5 more>; endpoint?: string; interval?: integer; batch?: object; … }[]`	optional
collectionInterval	`integer`	optional
retention	`{ period?: integer; downsampling?: object[] }`	optional
cardinalityLimits	`{ maxLabelCombinations?: integer; onLimitExceeded?: Enum<'drop' \| 'sample' \| 'alert'> }`	optional

ServiceLevelIndicator

Service Level Indicator

Properties

Property	Type	Required	Description
name	`string`	✅	SLI name (snake_case)
label	`string`	✅	Display label
description	`string`	optional	SLI description
metric	`string`	✅	Base metric name
type	`Enum<'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
enabled	`boolean`	optional

ServiceLevelObjective

Service Level Objective

Properties

Property	Type	Required	Description
name	`string`	✅	SLO name (snake_case)
label	`string`	✅	Display label
description	`string`	optional	SLO description
sli	`string`	✅	SLI name
target	`number`	✅	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 }[]`	✅
enabled	`boolean`	✅

TimeSeries

Time series

Properties

Property	Type	Required	Description
name	`string`	✅	Series name
labels	`Record<string, string>`	optional	Series labels
dataPoints	`{ timestamp: string; value: number; labels?: Record<string, string> }[]`	✅	Data points
startTime	`string`	optional	Start time
endTime	`string`	optional	End time

TimeSeriesDataPoint

Time series data point

Properties

Property	Type	Required	Description
timestamp	`string`	✅	Timestamp
value	`number`	✅	Value
labels	`Record<string, string>`	optional	Labels

On this page