Allows plugins to define and record custom counter, gauge, and histogram metrics, in addition to Kong’s built-in metrics. (Cannot be used in Pre/Post-Function plugins.)
Kong exports custom metrics automatically, together with its built-in metrics, through the OpenTelemetry plugin when a metric exporter is configured.
Register each metric once (e.g. as a plugin-module-level local variable,
or in your plugin’s init_worker handler), and keep the returned handle around to
record values against it later, typically from log or access:
-- once, e.g. at the top of your handler module
local custom_requests = kong.metrics.counter("my_plugin.request.count", {
description = "Number of requests processed by my_plugin",
unit = "{request}",
})
-- later, on every request
function MyPluginHandler:log(conf)
custom_requests:add(1, {
["my_plugin.service"] = conf.service,
status = "success",
})
endUse lowercase letters and a dot (.) to separate words in the metric name.
Follow the OpenTelemetry naming conventions:
https://opentelemetry.io/docs/specs/semconv/general/naming/
You must not register a new metric with a name that is already registered.
Each record call takes its own attributes as its second argument: a table of attribute name-value pairs. Two call sites of the same metric can therefore report different attributes:
custom_requests:add(1, { status = "success" })
custom_requests:add(1, { consumer = consumer.id })An attribute name must be a string that matches ^[a-z_][a-z0-9_.]*$.
An attribute value must be a string or a number. A string must not contain
,, {, or }. A number must not be NaN.
Kong rejects an invalid call: it logs an error and skips the call.
Registers a counter metric.
Parameters
string): metric name, must match ^[a-z_][a-z0-9_.]*$.table|nil): options:
description (string), unit (string),
value_type (kong.metrics.VALUE_TYPE.AS_INT or .AS_DOUBLE, defaults to AS_INT).Returns
table: a metric handle exposing handle:add(value, attributes).
value must be a non-negative, finite number. attributes is an optional
table of attribute name-value pairs.
On failure (invalid input or duplicate name), an error is logged and a
no-op handle is returned instead.Usage
local custom_requests = kong.metrics.counter("my_plugin.request.count", {
description = "Number of requests processed by my_plugin",
unit = "{request}",
})
custom_requests:add(1, {
["my_plugin.service"] = "example-service",
status = "success",
})Registers a gauge metric.
Parameters
string): metric name, must match ^[a-z_][a-z0-9_.]*$.table|nil): options:
description (string), unit (string),
value_type (kong.metrics.VALUE_TYPE.AS_INT or .AS_DOUBLE, defaults to AS_INT).Returns
table: a metric handle exposing handle:record(value, attributes)
and handle:add(delta, attributes). Both accept any finite number; unlike the
counter, delta may be negative to decrement the gauge. attributes is an
optional table of attribute name-value pairs.
On failure (invalid input or duplicate name), an error is logged and a
no-op handle is returned instead.Usage
local mysql_connections = kong.metrics.gauge("mysql.connection.count", {
description = "Number of mysql open connections",
unit = "{connection}",
})
mysql_connections:record(42)
mysql_connections:record(7, { ["mysql.host"] = "replica-1" })Registers a histogram metric.
Parameters
string): metric name, must match ^[a-z_][a-z0-9_.]*$.table|nil): options:
description (string), unit (string),
explicit_bounds (non-empty array of monotonically increasing positive numbers, optional;
defaults to millisecond-scale latency boundaries { 5, 10, 25, 50, 75, 100, 250, 500, 750, 1000, 2500, 5000, 7500, 10000 }).Returns
table: a metric handle exposing handle:record(value, attributes).
value must be a non-negative, finite number. attributes is an optional
table of attribute name-value pairs.
On failure (invalid input or duplicate name), an error is logged and a
no-op handle is returned instead.Usage
local upstream_latency = kong.metrics.histogram("my_plugin.upstream_latency", {
description = "Latency of my_plugin's upstream calls",
unit = "s",
explicit_bounds = { 0.01, 0.05, 0.1, 0.5, 1, 5 },
})
upstream_latency:record(0.234, { ["my_plugin.service"] = "example-service" })