STAP-EXPORTER(8)

💅 STAP-EXPORTER(8) 💅

okay bestie, welcome to STAP-EXPORTER(8) from the System Manager's Manual — this is the systemtap-prometheus interoperation mechanism and honestly? it's giving glow up ✨

---

✨ NAME ✨

stap-exporter — the whole systemtap ↔ prometheus interoperation situation, no cap 🫶

---

🌸 SYNOPSIS 🌸

stap-exporter [ OPTIONS ]

---

🦋 DESCRIPTION 🦋

so basically stap-exporter runs a lil squad of systemtap scripts and relays their procfs outputs to remote HTTP clients on demand. that means your systemtap scripts are directly usable as individual prometheus exporters, which is iconic honestly 💅. and it gets a lil help from a set of macros provided in the prometheus.stpm tapset file 🎀

---

👑 OPTIONS 👑

the stap-exporter program is obsessed with the following options, fr fr:

• -p, --port PORT — listen to the specified TCP port for HTTP requests. port 9900 is what gets used by default ✨
• -k, --keepalive KEEPALIVE — scripts that run longer than KEEPALIVE seconds beyond the last request get shut down 💀. there is no timeout by default, so once started, scripts are kept running.
• -s, --scripts SCRIPTS — search the directory SCRIPTS for *.stp files to be exposed. the default is given in the stappaths.7 man page 🫶
• -h, --help — print help message. that's it, that's the whole vibe 🌈

---

💖 OPERATION 💖

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 ⭐

---

🍓 EXAMPLE 🍓

suppose that example.stp contains the following script. it counts read syscalls on a per-thread & per-cpu basis, which is honestly such a flex 💅

       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 📊

---

🚨 SAFETY AND SECURITY 🚨

the stap-exporter server does not enforce any particular security mechanisms. so deploying it in an untrusted environment needs to consider the following, bestie. please actually read these 😭

🔒 script selection

since systemtap scripts are run under the privileges of the stap-exporter process (probably root), the system administrator must select only safe & robust scripts. check the scripts installed by default before activating the service. scripts cannot take input from the web clients 🛑

🔥 TCP/IP firewalling

since stap-exporter exposes the selected TCP/HTTP port to all interfaces on the host, it may be necessary to add a firewall. it is unlikely to be appropriate to expose such a service to an untrusted network 💀

🧱 HTTP filtering

since stap-exporter exposes the configured systemtap scripts to all HTTP clients without authentication, it may be necessary to protect it from abuse even on mostly trusted networks. an HTTP proxy may be used to impose URL- or client- or usage- or authentication-dependent filters 🎀

🔐 HTTPS

since stap-exporter speaks only plain HTTP, an HTTP proxy may be used to support HTTPS secure protocols ✨

---

👀 SEE ALSO 👀

stap(1), stapprobes(3stap), stappaths(7) tapset::prometheus(7)

---

💀 BUGS 💀

use the Bugzilla link of the project web page or our mailing list, fr fr:

http://sourceware.org/systemtap/, <systemtap@sourceware.org>

also: error::reporting(7stap), https://sourceware.org/systemtap/wiki/HowToReportBugs

---

and that's the whole page bestie 🫶 this was System Manager's Manual material, STAP-EXPORTER(8) — go forth and export your metrics, you main character 💅✨