stap-exporter(8)

1STAP-EXPORTER(8)            System Manager's Manual           STAP-EXPORTER(8)
2
3
4

NAME

6       stap-exporter - systemtap-prometheus interoperation mechanism
7
8
9
10

SYNOPSIS

12       stap-exporter [ OPTIONS ]
13
14

DESCRIPTION

16       stap-exporter  runs  a set of systemtap scripts and relays their procfs
17       outputs to remote HTTP clients on demand.  This makes systemtap scripts
18       directly  usable  as individual prometheus exporters.  This is assisted
19       by a set of macros provided in the prometheus.stpm tapset file.
20
21

OPTIONS

23       The stap-exporter program supports the following options.
24
25       -p --port PORT
26              Listen to the specified TCP port for HTTP requests. Port 9900 is
27              used by default.
28
29       -k --keepalive KEEPALIVE
30              Scripts  that  run longer than KEEPALIVE seconds beyond the last
31              request are shut down.  There is no timeout by default, so  once
32              started, scripts are kept running.
33
34       -s --scripts SCRIPTS
35              Search the directory SCRIPTS for *.stp files to be exposed.  The
36              default is given in the stappaths.7 man page.
37
38
39       -h --help
40              Print help message.
41
42
43

OPERATION

45       Upon startup, stap-exporter searches the directory specified by the  -s
46       directory  for files named *.stp.  The name of each file becomes avail‐
47       able as a URL component for subsequent GET HTTP requests.  For example,
48       when  an  HTTP  client  asks for /foo.stp, and the foo.stp script (exe‐
49       cutable / shell-script) was known, then it is spawned  with  additional
50       stap  options to set a module name.  This predictable module name makes
51       it possible for stap-exporter to transcribe a  procfs  file  from  that
52       running script to HTTP clients.
53
54       After  a  configurable  period  of disuse (-k or --keepalive option), a
55       systemtap script is terminated.  It will be restarted again if a client
56       requests.
57
58       All files whose name includes the substring autostart are started imme‐
59       diately (and restarted if they stop), rather than on-demand.  These are
60       excluded  from  keepalive considerations.  Scripts that may be too slow
61       to start or wish to report long-term statistics are candidates for this
62       treatment.
63
64

EXAMPLE

66       Suppose that example.stp contains the following script.  It counts read
67       syscalls on a per-thread & per-cpu basis.
68
69
70              global arr%
71
72              probe syscall.read {
73                  arr[tid(), cpu()]++
74              }
75
76              probe prometheus {
77                  @prometheus_dump_array2(arr, "count", "tid", "cpu")
78              }
79
80
81       The prometheus_dump_array macros are used to produce  metrics  from  an
82       array.   Systemtap  provides  a  prometheus_dump_arrayN macro for all N
83       from 1 to 8.  The first argument of the macros represents an array with
84       N-element keys.  The second argument represents the name of the metric.
85       The remaining N arguments represent the names of the metric's labels.
86
87       One may launch stap-exporter as root, or equivalent stapdev privileges,
88       then after a brief delay, use any web client to fetch data:
89
90
91              # stap-exporter -p 9999 -k 60 -c . &
92
93              $ curl http://localhost:9999/example.stp
94              Refresh page to access metrics.  [...]
95
96              $ curl http://localhost:9999/example.stp
97              count{tid="12614",cpu="0"} 9
98              count{tid="12170",cpu="3"} 107
99              count{tid="1802",cpu="0"} 33687
100              count{tid="12617",cpu="1"} 99
101              [...]
102
103
104       The  same  URL may be added to a Prometheus server's scrape_config sec‐
105       tion, or a Performance Co-Pilot pmdaprometheus config.d  directory,  to
106       collect this data into a monitoring system.
107
108
109

SAFETY AND SECURITY

111       The stap-exporter server does not enforce any particular security mech‐
112       anisms.  Therefore, deployment in an  untrusted  environment  needs  to
113       consider:
114
115
116       script selection
117              Since  systemtap  scripts  are  run  under the privileges of the
118              stap-exporter process (probably root), the system  administrator
119              must  select  only safe & robust scripts.  Check the scripts in‐
120              stalled by default before activating the service.  Scripts  can‐
121              not take input from the web clients.
122
123
124       TCP/IP firewalling
125              Since  stap-exporter  exposes  the selected TCP/HTTP port to all
126              interfaces on the host, it may be necessary to add  a  firewall.
127              It  is unlikely to be appropriate to expose such a service to an
128              untrusted network.
129
130
131       HTTP filtering
132              Since stap-exporter exposes the configured systemtap scripts  to
133              all  HTTP clients without authentication, it may be necessary to
134              protect it from abuse even on mostly trusted networks.  An  HTTP
135              proxy may be used to impose URL- or client- or usage- or authen‐
136              tication-dependent filters.
137
138
139       HTTPS  Since stap-exporter speaks only plain HTTP, an HTTP proxy may be
140              used to support HTTPS secure protocols.
141
142
143

BUGS

149       Use  the  Bugzilla  link  of  the project web page or our mailing list.
150       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
151
152       error::reporting(7stap),
153       https://sourceware.org/systemtap/wiki/HowToReportBugs
154
155
156
157                                                              STAP-EXPORTER(8)