Metrics & Telemetry

The metrics module records application counters, gauges, and histogram observations.

This is an API reference. The snippets show one observation at a time and propagate collector errors.

Every function returns true, nil after passing the observation to the active collector. If the execution context has no collector, it returns nil and a non-retryable errors.INTERNAL error.

Labels are optional. Only entries with both a string key and a string value are recorded; other entries are silently ignored. A non-table labels argument is treated as if no labels were supplied.

Metric names are forwarded without local validation.

Loading

local metrics = require("metrics")

Counters

metrics.counter_inc

Increment a counter by one.

local recorded, err = metrics.counter_inc("requests_total", {method = "POST"})
if err then return nil, err end
return recorded

Returns: boolean, error

metrics.counter_add

Add a value to a counter.

local recorded, err = metrics.counter_add("bytes_total", 1024, {direction = "out"})
if err then return nil, err end
return recorded

Returns: boolean, error

The runtime forwards the value unchanged and does not require it to be positive.

Gauges

metrics.gauge_set

Set a gauge to the current value.

local recorded, err = metrics.gauge_set("queue_depth", 42, {queue = "emails"})
if err then return nil, err end
return recorded

Returns: boolean, error

metrics.gauge_inc

Increment a gauge by one.

local recorded, err = metrics.gauge_inc("connections", {pool = "db"})
if err then return nil, err end
return recorded

Returns: boolean, error

metrics.gauge_dec

Decrement a gauge by one.

local recorded, err = metrics.gauge_dec("connections", {pool = "db"})
if err then return nil, err end
return recorded

Returns: boolean, error

Histograms

metrics.histogram

Record a histogram observation.

local recorded, err = metrics.histogram("duration_seconds", 0.123, {method = "GET"})
if err then return nil, err end
return recorded

Returns: boolean, error

Errors

Invalid name or value types raise Lua argument errors instead of returning structured errors.

See Error Handling for working with errors.