Skip to main content
The metrics section defines Prometheus metrics that queries can update. Metric names must be valid Prometheus metric identifiers.

​
Basic Configuration

metrics:
  my_gauge:
    type: gauge
    description: A sample gauge metric

​
Configuration Options

​
type
enum
required
The type of the Prometheus metric.Available types:
  • counter: Value is incremented or set with each result from queries
  • gauge: Value is set with each result from queries
  • histogram: Each result from queries is added to observations
  • summary: Each result from queries is added to observations
  • enum: Value is set to one of predefined states with each result
​
description
string
An optional description of the metric. This appears in the Prometheus /metrics endpoint and helps document what the metric represents.
​
labels
array[string]
Optional list of label names to apply to the metric. Label names must match the pattern ^[a-zA-Z_][a-zA-Z0-9_]*$.When specified, queries updating the metric must return columns with names matching both the metric name and all label names.
​
buckets
array[float]
For histogram metrics only. Defines the bucket boundaries for the histogram.
  • Must contain at least 1 value
  • Values must be sorted in ascending order
  • Values must be unique
  • If not specified, Prometheus default buckets are used: [.005, .01, .025, .05, .075, .1, .25, .5, .75, 1.0, 2.5, 5.0, 7.5, 10.0, +Inf]
​
states
array[string]
For enum metrics only. List of possible string values for the enum state.
  • Must contain at least 1 value
  • Values must be unique
  • Queries must return one of these exact states
​
expiration
string | integer
The amount of time after which a metric series is cleared if no new value is collected.The value can be:
  • An integer (interpreted as seconds)
  • A string with suffix: s (seconds), m (minutes), h (hours), d (days)
Examples: 300, 5m, 24h, 7dLast report times are tracked independently for each set of label values, making this useful for metric series that only exist temporarily.
​
increment
boolean
default:"false"
For counter metrics only. Controls whether to increment the counter by the query result or set it to the result.
  • false (default): Counter is set to the value returned by the query
  • true: Counter is incremented by the value returned by the query

​
Metric Types

​
Counter

Counters track cumulative values that only increase (or are reset to zero). 
metrics:
  total_requests:
    type: counter
    description: Total number of requests
With increment behavior: 
metrics:
  request_count:
    type: counter
    description: Request count
    increment: true  # Add query result to current value

​
Gauge

Gauges represent values that can go up or down. 
metrics:
  active_connections:
    type: gauge
    description: Number of active database connections

​
Histogram

Histograms sample observations and count them in configurable buckets. 
metrics:
  query_duration:
    type: histogram
    description: Query execution duration in seconds
    buckets: [0.1, 0.5, 1.0, 2.0, 5.0, 10.0]
Histograms are useful for measuring request durations or response sizes where you want to analyze the distribution of values.

​
Summary

Summaries also sample observations but calculate configurable quantiles over a sliding time window. 
metrics:
  response_size:
    type: summary
    description: Response size in bytes
Summaries are similar to histograms but calculate quantiles on the client side. Use histograms when you need server-side aggregation across multiple instances.

​
Enum

Enums represent a state that can be one of a predefined set of string values. 
metrics:
  service_status:
    type: enum
    description: Current service status
    states: [starting, running, stopping, stopped, error]
Queries updating enum metrics must return one of the exact state values defined in the states list.

​
Labels

Labels add dimensions to metrics, allowing you to differentiate between different instances: 
metrics:
  http_requests:
    type: counter
    description: HTTP requests by method and status
    labels: [method, status]
Query must return matching columns: 
SELECT 
  COUNT(*) AS http_requests,
  method,
  status
FROM request_log
GROUP BY method, status
All queries updating this metric will automatically include a database label to identify which database the metric came from.

​
Expiration

Use expiration to automatically clean up metric series that haven’t been updated: 
metrics:
  user_session_duration:
    type: gauge
    description: Duration of user sessions
    labels: [user_id]
    expiration: 1h  # Clear series if not updated for 1 hour
This is useful when:
  • Metrics are tied to ephemeral resources (sessions, temporary jobs)
  • You want to avoid unbounded cardinality growth
  • Series naturally expire after some time

​
Complete Examples

​
PostgreSQL Connection Stats

metrics:
  pg_connections_active:
    type: gauge
    description: Number of active PostgreSQL connections
    labels: [state]
  
  pg_transaction_commits:
    type: counter
    description: Number of committed transactions
    labels: [database]
  
  pg_query_duration:
    type: histogram
    description: PostgreSQL query duration in seconds
    buckets: [0.001, 0.01, 0.1, 0.5, 1.0, 5.0]
    labels: [database, user]

​
Application Metrics

metrics:
  app_users_online:
    type: gauge
    description: Number of users currently online
  
  app_requests_total:
    type: counter
    description: Total application requests
    labels: [endpoint, method, status]
    increment: true
  
  app_error_rate:
    type: gauge
    description: Application error rate (errors per second)
  
  app_task_status:
    type: enum
    description: Current status of background tasks
    states: [pending, running, completed, failed]
    labels: [task_name]
  
  app_cache_hit_ratio:
    type: gauge
    description: Cache hit ratio percentage
    labels: [cache_name]
  
  app_session_duration:
    type: histogram
    description: User session duration in minutes
    buckets: [1, 5, 10, 30, 60, 120, 240]
    expiration: 2h

​
Business Metrics

metrics:
  orders_total:
    type: counter
    description: Total number of orders
    labels: [status, region]
  
  revenue_total:
    type: counter
    description: Total revenue in cents
    labels: [currency, region]
  
  inventory_items:
    type: gauge
    description: Current inventory item count
    labels: [product_id, warehouse]
    expiration: 30m
  
  order_processing_time:
    type: histogram
    description: Order processing time in seconds
    buckets: [10, 30, 60, 120, 300, 600]
    labels: [order_type]

​
Reserved Metric Names

The following metric names are reserved for built-in metrics and cannot be used:
  • database_errors
  • queries
  • query_interval
  • query_latency
  • query_timestamp
See Built-in Metrics for more information.

​
Reserved Label Names

The database label is automatically added to all metrics and cannot be used in your custom labels. If you configure database-level labels, those label names are also reserved and cannot be used in metric definitions.

Build docs developers (and LLMs) love

Get started for freeTalk to us