stap-exporter
[
OPTIONS
]
stap-exporter runs a set of systemtap scripts and relays their procfs outputs to remote HTTP clients on demand. This makes systemtap scripts directly usable as individual prometheus exporters. This is assisted by a set of macros provided in the prometheus.stpm tapset file.
The stap-exporter program supports the following options.
Upon startup, stap-exporter searches the directory specified by the -s directory for files named *.stp. The name of each file becomes available as a URL component for subsequent GET HTTP requests. For example, when an HTTP client asks for /foo.stp, and the foo.stp script (executable / shell-script) was known, then it is spawned with additional stap options to set a module name. This predictable module name makes it possible for stap-exporter to transcribe a procfs file from that running script to HTTP clients.
After a configurable period of disuse (-k or --keepalive option), a systemtap script is terminated. It will be restarted again if a client requests.
All files whose name includes the substring autostart are started immediately (and restarted if they stop), rather than on-demand. These are excluded from keepalive considerations. Scripts that may be too slow to start or wish to report long-term statistics are candidates for this treatment.
Suppose that example.stp contains the following script. It counts read syscalls on a per-thread & per-cpu basis.
global arr% probe syscall.read { arr[tid(), cpu()]++ } probe prometheus { @prometheus_dump_array2(arr, "count", "tid", "cpu") }
The prometheus_dump_array macros are used to produce metrics from an array. Systemtap provides a prometheus_dump_arrayN macro for all N from 1 to 8. The first argument of the macros represents an array with N-element keys. The second argument represents the name of the metric. The remaining N arguments represent the names of the metric's labels.
One may launch stap-exporter as root, or equivalent stapdev privileges, then after a brief delay, use any web client to fetch data:
# stap-exporter -p 9999 -k 60 -c . & $ curl http://localhost:9999/example.stp Refresh page to access metrics. [...] $ curl http://localhost:9999/example.stp count{tid="12614",cpu="0"} 9 count{tid="12170",cpu="3"} 107 count{tid="1802",cpu="0"} 33687 count{tid="12617",cpu="1"} 99 [...]
The same URL may be added to a Prometheus server's scrape_config section, or a Performance Co-Pilot pmdaprometheus config.d directory, to collect this data into a monitoring system.
The stap-exporter server does not enforce any particular security mechanisms. Therefore, deployment in an untrusted environment needs to consider:
error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs