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

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

Parameters:name (str) – The metric to retrieve

New in version 4.5.0.

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

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

New 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.