Skip to content

Metric names

Every metric instrument emits, against its Prometheus counterpart in go/transport-metrics. Metric names are part of the module's compatibility contract, and RED, USE and cardinality says why they differ.

The API is on pkg.go.dev.

Operations

OTel metric Instrument Unit Attributes Prometheus metric
operation.duration histogram s operation.name, error.type on failure operation_duration_seconds
(its count) operations_total
(its count with error.type) operation_errors_total
operation.active up/down counter {operation} operation.name operations_in_flight

DB

Every query metric carries db.namespace, the name given to NewDB. Every pool metric carries db.client.connection.pool.name, the same name.

OTel metric Instrument Unit Other attributes Prometheus metric
db.client.operation.duration histogram s db.operation.name, db.system.name, error.type on failure db_query_duration_seconds
(its count) db_queries_total
(its count with error.type) db_query_errors_total
phpboyscout.db.client.operation.active up/down counter {operation} db.operation.name db_queries_in_flight
db.client.connection.count observable up/down counter {connection} db.client.connection.state (used, idle) db_pool_in_use, db_pool_idle
(its sum over state) db_pool_open
db.client.connection.max observable up/down counter {connection} db_pool_max_open
phpboyscout.db.client.connection.wait_count observable counter {wait} db_pool_wait_count_total
phpboyscout.db.client.connection.wait_time observable counter s db_pool_wait_seconds_total

The phpboyscout. names have no semantic convention to follow. Convention's db.client.connection.wait_time is a histogram of individual waits, which a cumulative total cannot feed, so phpboyscout.db.client.connection.wait_time is a counter under the same word. Only db.client.operation.duration is a Stable convention. The db.client.connection.* metrics are in Development.

Cache

Every cache metric carries cache.name, the name given to NewCache.

OTel metric Instrument Unit Other attributes Prometheus metric
cache.operations counter {operation} cache.result (hit, miss) cache_hits_total, cache_misses_total
cache.evictions counter {entry} cache_evictions_total
cache.size observable gauge {entry} cache_size
cache.capacity observable gauge {entry} cache_capacity

CircuitBreaker

Every breaker metric carries circuit_breaker.name, the name given to NewCircuitBreaker.

OTel metric Instrument Unit Prometheus metric
circuit_breaker.state observable gauge {state} circuit_breaker_state
circuit_breaker.trips counter {trip} circuit_breaker_trips_total
circuit_breaker.short_circuits counter {request} circuit_breaker_short_circuits_total
circuit_breaker.successes counter {request} circuit_breaker_successes_total
circuit_breaker.failures counter {request} circuit_breaker_failures_total

The state reads 0 for closed, 1 for open and 2 for half-open, as it does in transport-metrics.

Queue

Every queue metric carries queue.name, the name given to NewQueue.

OTel metric Instrument Unit Prometheus metric
queue.depth up/down counter {item} queue_depth
queue.enqueued counter {item} queue_enqueued_total
queue.dequeued counter {item} queue_dequeued_total
queue.wait.duration histogram s queue_wait_seconds
queue.processing.duration histogram s queue_processing_seconds

API differences

transport-metrics instrument Why
m.NewOperations(opts...) NewOperations(meter, opts...) Takes an explicit meter; there is no registry to hang a method on
ObserveResult(o, ctx, name, fn) ObserveResult(ctx, o, name, fn) Context first, the Go convention
m.NewDB(name, opts...) NewDB(meter, name, opts...) As above
(none) WithDBSystem(name) Semantic conventions require db.system.name
(none) DB.Close() An OTel callback must be unregistered, or it keeps the pool alive
m.NewCache(name, opts...) NewCache(meter, name, opts...) As above
cache.Hit(), Miss(), Eviction(n) cache.Hit(ctx), Miss(ctx), Eviction(ctx, n) A measurement without a context carries no exemplar
(none) Cache.Close() An OTel callback must be unregistered
cache.Eviction(n) panics on a negative n cache.Eviction(ctx, n) ignores an n below 1 A counter cannot go down, and a metrics call should not take a service down
m.NewCircuitBreaker(name, opts...) NewCircuitBreaker(meter, name, opts...) As above
cb.Trip(), ShortCircuit(), Success(), Failure() The same, taking ctx A measurement without a context carries no exemplar
(none) CircuitBreaker.Close() An OTel callback must be unregistered
m.NewQueue(name, opts...) NewQueue(meter, name, opts...) As above
q.Enqueue(), Dequeue(), ObserveWait(d) The same, taking ctx A measurement without a context carries no exemplar
WithConstLabels(labels) WithAttributes(attrs...) OTel's vocabulary
WithNamespace(ns) (none) The meter's name scopes its instruments, and a prefix would break semantic-convention names