Lua Scripting and Statistics¶

The Lua engine can generate and retrieve metrics.

Generating Metrics¶

Custom metrics can be added which will be shown in the output of ‘rec_control get-all’ and sent to the metrics server over the Carbon protocol. They will also appear in the JSON HTTP API.

Create a custom metric with:

myMetric = getMetric("myspecialmetric")

getMetric(name[, prometheusName]): Metric¶

getMetric(name[, prometheusName | prometheusTable]): Metric

Returns the Metric object with the name name, creating the metric if it does not exist.

Parameters:¶: name (str) – The metric to retrieve

Added in version 4.5.0.

Parameters:¶: prometheusName (string) – The optional Prometheus specific name.

Added in version 5.4.0.

Parameters:¶: prometheusTable (table) – The optional table of Prometheus specific options

The elements of prometheusTable can be:

Keyword,	Type,	Description
`prometheusName`	`string`	The optional Prometheus specific name
`type`	`string`	The optional Prometheus metric type (`"counter"` or `"gauge"`)
`description`	`string`	The optional Prometheus metric description

class Metric¶

Represents a custom metric

Metric(): inc()¶: Increase metric by 1

Metric(): incBy(amount)¶

Increase metric by amount

Parameters:¶: amount (int)

Metric(): set(to)¶

Set metric to value to

Parameters:¶: to (int)

Metric(): get(): int¶: Get value of metric

Metrics are shared across all of PowerDNS and are fully atomic and high performance. A Metric object is effectively a pointer to an atomic value.

Note that metrics live in the same namespace as ‘system’ metrics. So if you generate one that overlaps with a PowerDNS stock metric, you will get double output and weird results.

Looking at Statistics¶

Added in version 4.1.0.

Statistics can be retrieved from Lua using the getStat() call.

getStat(name): int¶

Returns the value of a statistic.

Parameters:¶: name (string) – The name of the statistic.

For example, to retrieve the number of cache misses:

cacheMisses = getStat("cache-misses")

Please be aware that retrieving statistics is a relatively costly operation, and as such should for example not be done for every query.