Skip to main content
The metrics section defines the Prometheus metrics that queries will populate. Each metric is configured with a unique name as the key.

​
Metric Structure

​
metrics
object
required
Dictionary of metric configurations, keyed by metric name.Metric names must match the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$ (start with letter or underscore, followed by letters, numbers, or underscores).
metrics:
  http_requests_total:
    type: counter
    description: Total HTTP requests
    labels: [method, status]

​
Metric Fields

​
type
string
required
The Prometheus metric type.Valid values:
  • counter - A cumulative metric that only increases
  • gauge - A metric that can increase or decrease
  • histogram - Samples observations and counts them in configurable buckets
  • summary - Similar to histogram, provides quantiles over a sliding time window
  • enum - A metric that can take one of a set of string values
metrics:
  requests_total:
    type: counter
​
description
string
default:""
Human-readable description of the metric.This description is included in the Prometheus metric metadata.
metrics:
  requests_total:
    type: counter
    description: Total number of HTTP requests received
​
labels
array
default:"[]"
List of label names for the metric.Labels allow the metric to be sliced and diced in different dimensions. Query results must include columns matching these label names.Constraints:
  • If specified, must contain at least 1 label
  • Label names must match the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$
metrics:
  http_requests_total:
    type: counter
    labels: [method, status, endpoint]

​
Type-Specific Fields

​
Histogram Fields

​
buckets
array
Bucket boundaries for histogram metrics.Required for: histogram type metricsConstraints:
  • Must contain at least 1 value
  • Values must be unique
  • Values must be sorted in ascending order
  • Values must be numeric (float)
metrics:
  request_duration:
    type: histogram
    description: Request duration in seconds
    buckets: [0.1, 0.5, 1.0, 2.0, 5.0, 10.0]

​
Enum Fields

​
states
array
Valid state values for enum metrics.Required for: enum type metrics
Only valid for: enum type metricsConstraints:
  • Must contain at least 1 state
  • States must be unique
Validation: Setting states on non-enum metrics will raise: ValueError: states can only be set for enum metrics
metrics:
  database_status:
    type: enum
    description: Current database status
    states: [online, offline, maintenance, degraded]

​
Counter Fields

​
increment
boolean
default:"false"
Whether to increment the counter by the query result value or set it directly.Only valid for: counter type metricsWhen true, the value from the query is added to the current counter value. When false, the counter is set to the query value (useful when the query returns cumulative counts).Default: falseValidation: Setting increment: true on non-counter metrics will raise: ValueError: increment can only be set for counter metrics
metrics:
  new_events:
    type: counter
    description: New events since last query
    increment: true

​
Time-Based Fields

​
expiration
string | integer
Time after which metric series are removed if not updated.Valid for: All metric typesUseful for cleaning up metrics for entities that no longer exist (e.g., deleted users, removed servers).Format:
  • Integer: seconds
  • String: number followed by optional suffix (s=seconds, m=minutes, h=hours, d=days)
Constraints:
  • Must be a positive number
  • Must match pattern ^[0-9]+[smhd]?$ for string format
metrics:
  user_activity:
    type: gauge
    labels: [user_id]
    expiration: 24h  # Remove user metrics after 24 hours of inactivity

​
Metric Type Examples

​
Counter

Counters represent cumulative values that only increase (or reset to zero). 
metrics:
  http_requests_total:
    type: counter
    description: Total HTTP requests
    labels: [method, status]
  
  # Counter with increment mode
  new_orders:
    type: counter
    description: New orders received
    increment: true

​
Gauge

Gauges represent values that can go up or down. 
metrics:
  active_connections:
    type: gauge
    description: Number of active database connections
    labels: [database]
  
  cpu_usage_percent:
    type: gauge
    description: CPU usage percentage
    expiration: 5m

​
Histogram

Histograms sample observations and count them in configurable buckets. 
metrics:
  query_duration_seconds:
    type: histogram
    description: Query execution time in seconds
    labels: [query_name]
    buckets: [0.001, 0.01, 0.1, 0.5, 1.0, 5.0, 10.0]
  
  response_size_bytes:
    type: histogram
    description: Response size in bytes
    buckets: [100, 1000, 10000, 100000, 1000000]

​
Summary

Summaries are similar to histograms but calculate quantiles on the client side. 
metrics:
  request_latency:
    type: summary
    description: Request latency in seconds
    labels: [endpoint]
  
  payload_size:
    type: summary
    description: Payload size in bytes

​
Enum

Enums represent metrics that can take one of a predefined set of string values. 
metrics:
  service_status:
    type: enum
    description: Current service status
    labels: [service_name]
    states: [starting, running, stopping, stopped, error]
  
  replication_state:
    type: enum
    description: Database replication state
    labels: [replica_id]
    states: [streaming, catchup, disconnected]

​
Complete Example

metrics:
  # Counter metric
  db_queries_total:
    type: counter
    description: Total database queries executed
    labels: [database, query_type]
  
  # Gauge metric with expiration
  active_sessions:
    type: gauge
    description: Number of active database sessions
    labels: [database, user]
    expiration: 30m
  
  # Histogram metric
  query_duration_seconds:
    type: histogram
    description: Query execution duration in seconds
    labels: [database, query_name]
    buckets: [0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0, 30.0]
  
  # Summary metric
  transaction_size:
    type: summary
    description: Transaction size in rows
    labels: [database]
  
  # Enum metric
  database_state:
    type: enum
    description: Current database state
    labels: [database]
    states: [online, offline, readonly, maintenance]
  
  # Counter with increment
  new_connections:
    type: counter
    description: New connections established
    labels: [database]
    increment: true

​
Validation Rules

The following validation rules are enforced on metric configurations:
  1. Type validation:
    • type must be one of: counter, gauge, histogram, summary, enum
  2. Label validation:
    • Label names must match pattern ^[a-zA-Z_][a-zA-Z0-9_]*$
    • If labels is specified, must contain at least 1 label
  3. Histogram validation:
    • buckets must contain at least 1 value
    • Bucket values must be unique
    • Bucket values must be sorted in ascending order
  4. Enum validation:
    • states can only be set for enum type metrics
    • states must contain at least 1 value
    • State values must be unique
  5. Counter validation:
    • increment can only be set to true for counter type metrics
  6. Expiration validation:
    • Must be a positive number
    • String format must match ^[0-9]+[smhd]?$

​
Error Messages

Common validation errors:
  • ValueError: states can only be set for enum metrics - Attempted to set states on a non-enum metric
  • ValueError: increment can only be set for counter metrics - Attempted to set increment: true on a non-counter metric
  • AssertionError: must not contain duplicate items - Duplicate values in buckets or states
  • AssertionError: items must be sorted - Bucket values are not in ascending order
  • AssertionError: must be a positive number - Invalid expiration value

Build docs developers (and LLMs) love

Get started for freeTalk to us