mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-19 10:58:17 +00:00
Wez Furlong
87b64c8d2b
Give some suggestions on how to interpret a number of the metrics, as well as cross linking to relevant documentation for them.
76 lines
2.3 KiB
Markdown
76 lines
2.3 KiB
Markdown
# kumo.time.start_timer
|
|
|
|
```lua
|
|
kumo.time.start_timer(LABEL)
|
|
```
|
|
|
|
{{since('2025.01.23-7273d2bc')}}
|
|
|
|
Starts a timer with a specific label and returns a timer object.
|
|
|
|
The timer object can be used to update a latency histogram that is reported in
|
|
the prometheus metrics for the server to track how long it takes for a certain
|
|
operation to complete.
|
|
|
|
See [user_lua_latency](../metrics/kumod/user_lua_latency.md) for information
|
|
about the exported histogram.
|
|
|
|
The most basic usage looks like this:
|
|
|
|
```lua
|
|
local timer = kumo.time.start_timer 'my-operation'
|
|
|
|
-- do something here
|
|
kumo.time.sleep(1.5)
|
|
|
|
-- And record the latency
|
|
timer:done()
|
|
```
|
|
|
|
After this runs, you will see the following metrics:
|
|
|
|
```console
|
|
$ curl -s 'http://127.0.0.1:8000/metrics' | grep user_lua
|
|
# HELP user_lua_latency how long something user-defined took to run in your lua policy
|
|
# TYPE user_lua_latency histogram
|
|
user_lua_latency_bucket{label="my-operation",le="0.005"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="0.01"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="0.025"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="0.05"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="0.1"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="0.25"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="0.5"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="1"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="2.5"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="5"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="10"} 1
|
|
user_lua_latency_bucket{label="my-operation",le="+Inf"} 1
|
|
user_lua_latency_sum{label="my-operation"} 1.5
|
|
user_lua_latency_count{label="my-operation"} 1
|
|
```
|
|
|
|
You can use the `<close>` feature of lua to automatically trigger the `:done()` call
|
|
when the timer object falls out of scope. This is useful for example to track how
|
|
long it takes to run a function:
|
|
|
|
```
|
|
local function mything()
|
|
-- This `timer` will automatically report the duration of the `mything`
|
|
-- function when it returns, so you don't need to litter the function
|
|
-- with timer:done() calls for each return case below
|
|
local timer <close> = kumo.time.start_timer("mything")
|
|
|
|
if something then
|
|
return
|
|
end
|
|
|
|
if something_else then
|
|
return
|
|
end
|
|
|
|
end
|
|
```
|
|
|
|
The `timer:done()` method returns the number of seconds that have elapsed
|
|
since the timer was started.
|