Prometheus
Create collectors (create_*_vec) in an init script. Policy callbacks (environment sources, subject sources, and actions) can update existing collectors but cannot create them. See Lua runtimes and capabilities.
Nauthilus has basic support for some Prometheus metrics.
local nauthilus_prometheus = require("nauthilus_prometheus")
Registration semantics
Each create_*_vec call registers its collector with the process-wide Prometheus registry. Creating a metric whose
name was already created by any Lua script in this process is a no-op. If a collector with the same name was
registered by other Go code, for example by a native plugin, Nauthilus reuses it when it is the same metric type
and its complete descriptor (name, help text, and label names) is identical. A collector with the same name but a
different type or descriptor raises the Lua error register Prometheus metric "<name>": ... instead of panicking. Keep the
help text and labels of a metric name identical in every script that creates it.
Gauge vector
You must create a gauge vector first before using it. This should be done in an init script.
nauthilus_prometheus.create_gauge_vec
Creates a Prometheus gauge vector with specified name, help text, and labels.
Syntax
nauthilus_prometheus.create_gauge_vec(name, help, labels)
Parameters
name(string): The name of the gauge vectorhelp(string): Description text for the gauge vectorlabels(table): A Lua table containing label names
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "http_client_concurrent_requests_total"
local help = "Measure the number of total concurrent HTTP client requests"
local labels = { "service" }
nauthilus_prometheus.create_gauge_vec(name, help, labels)
nauthilus_prometheus.add_gauge
Adds a value to a gauge with specified labels.
Syntax
nauthilus_prometheus.add_gauge(name, value, labels)
Parameters
name(string): The name of the gauge vectorvalue(number): The value to add to the gaugelabels(table): A Lua table containing label values
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_gauge_name"
local value = 42
local labels = { "some label" }
nauthilus_prometheus.add_gauge(name, value, labels)
nauthilus_prometheus.sub_gauge
Subtracts a value from a gauge with specified labels.
Syntax
nauthilus_prometheus.sub_gauge(name, value, labels)
Parameters
name(string): The name of the gauge vectorvalue(number): The value to subtract from the gaugelabels(table): A Lua table containing label values
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_gauge_name"
local value = 42
local labels = { "some label" }
nauthilus_prometheus.sub_gauge(name, value, labels)
nauthilus_prometheus.set_gauge
Sets a gauge to a specific value with specified labels.
Syntax
nauthilus_prometheus.set_gauge(name, value, labels)
Parameters
name(string): The name of the gauge vectorvalue(number): The value to set the gauge tolabels(table): A Lua table containing label values
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_gauge_name"
local value = 42
local labels = { "some label" }
nauthilus_prometheus.set_gauge(name, value, labels)
nauthilus_prometheus.increment_gauge
Increments a gauge counter by 1 with specified labels.
Syntax
nauthilus_prometheus.increment_gauge(name, labels)
Parameters
name(string): The name of the gauge vectorlabels(table): A Lua table containing label key-value pairs
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "http_client_concurrent_requests_total"
nauthilus_prometheus.increment_gauge(name, { service = "some_service_name" })
nauthilus_prometheus.decrement_gauge
Decrements a gauge counter by 1 with specified labels.
Syntax
nauthilus_prometheus.decrement_gauge(name, labels)
Parameters
name(string): The name of the gauge vectorlabels(table): A Lua table containing label key-value pairs
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "http_client_concurrent_requests_total"
nauthilus_prometheus.decrement_gauge(name, { service = "some_service_name" })
Counter vector
You must create a counter vector first before using it. This should be done in an init script.
nauthilus_prometheus.create_counter_vec
Creates a Prometheus counter vector with specified name, help text, and labels.
Syntax
nauthilus_prometheus.create_counter_vec(name, help, labels)
Parameters
name(string): The name of the counter vectorhelp(string): Description text for the counter vectorlabels(table): A Lua table containing label names
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_name"
local help = "Some description for this counter vector"
local labels = { "some_label"}
nauthilus_prometheus.create_counter_vec(name, help, labels)
nauthilus_prometheus.increment_counter
Increments a counter by 1 with specified labels.
Syntax
nauthilus_prometheus.increment_counter(name, labels)
Parameters
name(string): The name of the counter vectorlabels(table): A Lua table containing label values
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_counter_name"
local labels = { "some_label" }
nauthilus_prometheus.increment_counter(name, labels)
Summary vector
You must create a summary vector first before using it. This should be done in an init script.
nauthilus_prometheus.create_summary_vec
Creates a Prometheus summary vector with specified name, help text, and labels.
Syntax
nauthilus_prometheus.create_summary_vec(name, help, labels)
Parameters
name(string): The name of the summary vectorhelp(string): Description text for the summary vectorlabels(table): A Lua table containing label names
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_name"
local help = "Some description for this summary vector"
local labels = { "some_label"}
nauthilus_prometheus.create_summary_vec(name, help, labels)
nauthilus_prometheus.start_summary_timer
Starts a timer for a summary vector with specified labels.
Syntax
local timer = nauthilus_prometheus.start_summary_timer(name, labels)
Parameters
name(string): The name of the summary vectorlabels(table): A Lua table containing label values
Returns
timer(userdata): A timer object that can be passed to stop_timer
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_name"
local labels = { "some_label" }
local user_data_timer = nauthilus_prometheus.start_summary_timer(name, labels)
nauthilus_prometheus.stop_timer
Stops a timer and records the elapsed time in the associated vector.
Syntax
nauthilus_prometheus.stop_timer(timer)
Parameters
timer(userdata): A timer object returned from start_summary_timer or start_histogram_timer
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
-- First start a timer
local name = "some_name"
local labels = { "some_label" }
local user_data_timer = nauthilus_prometheus.start_summary_timer(name, labels)
-- Do some work...
-- Then stop the timer
nauthilus_prometheus.stop_timer(user_data_timer)
Histogram vector
You must create a histogram vector first before using it. This should be done in an init script.
nauthilus_prometheus.create_histogram_vec
Creates a Prometheus histogram vector with specified name, help text, and labels.
Syntax
nauthilus_prometheus.create_histogram_vec(name, help, labels)
Parameters
name(string): The name of the histogram vectorhelp(string): Description text for the histogram vectorlabels(table): A Lua table containing label names
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_name"
local help = "Some description for this histogram vector"
local labels = { "some_label"}
nauthilus_prometheus.create_histogram_vec(name, help, labels)
nauthilus_prometheus.start_histogram_timer
Starts a timer for a histogram vector with specified labels.
Syntax
local timer = nauthilus_prometheus.start_histogram_timer(name, labels)
Parameters
name(string): The name of the histogram vectorlabels(table): A Lua table containing label values
Returns
timer(userdata): A timer object that can be passed to stop_timer
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
local name = "some_name"
local labels = { "some_label" }
local user_data_timer = nauthilus_prometheus.start_histogram_timer(name, labels)
nauthilus_prometheus.stop_timer
Stops a histogram timer and records the elapsed time in the associated vector.
Syntax
nauthilus_prometheus.stop_timer(timer)
Parameters
timer(userdata): A timer object returned from start_histogram_timer
Returns
None
Example
local nauthilus_prometheus = require("nauthilus_prometheus")
-- First start a timer
local name = "some_name"
local labels = { "some_label" }
local user_data_timer = nauthilus_prometheus.start_histogram_timer(name, labels)
-- Do some work...
-- Then stop the timer
nauthilus_prometheus.stop_timer(user_data_timer)