systemtap-stap-exporter/stap-exporter(8)

1STAPBPF(8)                  System Manager's Manual                 STAPBPF(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  is  a  small  program that manages systemtap session and
17       relays prometheus metrics from the sessions  to  remote  requesters  on
18       demand.  stap-exporter  runs as a systemd service and listens to a con‐
19       figurable TCP port for requests. stap-exporter is  capable  of  running
20       multiple  stap scripts at a time. Metrics for a given script are avail‐
21       able at the URL [HOSTNAME]:[PORT]/[SCRIPTNAME]. PORT defaults  to  9900
22       but  is  configurable, see OPTIONS below. After installation, the stap-
23       exporter systemd service should be manually enabled.
24
25
26       If stap-exporter receives a request for metrics from a script  that  is
27       already  running, the script's prometheus probes will trigger. The met‐
28       rics  sent  back   to   the   requester   are   specified   using   the
29       prometheus_dump_arrayN  family of macros (see EXAMPLE below).  If stap-
30       exporter receives a request for a script that is not currently running,
31       stap-exporter  will  search  systemtap.examples for scripts with script
32       name given in the URL.  If found, stap-exporter will begin running this
33       script.  At  launch,  stap-exporter  will automatically run all scripts
34       found in systemtap.examples/stap-exporter-scripts.
35
36
37

OPTIONS

39       The stap-exporter program supports the  following  options.  Any  other
40       option prints a list of supported options.
41
42       -p --port
43              Listen to the specified TCP port for requests. Port 9900 is used
44              by default.
45
46       -t --timeout
47              Scripts that run longer than TIMEOUT seconds will  be  automati‐
48              cally  shutdown.  Each time stap-exporter recieves a request for
49              a particular script, it  resets  that  script's  remaining  time
50              until shutdown. By default, scripts will run until stap-exporter
51              is terminated.
52
53       -h --help
54              Print help message.
55
56

EXAMPLES

58       Suppose that example.stp contains the following stap script:
59
60
61              global arr
62
63              probe syscall.read {
64                  arr[tid(), cpu()]++
65              }
66
67              probe prometheus {
68                  @prometheus_dump_array2(arr, "count", "tid", "cpu")
69              }
70
71
72       The prometheus_dump_arrayN macros are used to produce metrics  from  an
73       array.   Systemtap  provides  a  prometheus_dump_arrayN macro for all N
74       from 1 to 8.  The first argument of the macros represents an array with
75       N-element keys.  The second argument represents the name of the metric.
76       The remaining N arguments represent the names of the metric's labels.
77
78
79              $ stap-exporter -p 9999 -t 60
80
81              $ curl localhost:9999/example.stp
82              Refresh page to access metrics.
83
84              $ curl localhost:9999/example.stp
85              count{tid="12614",cpu="0"} 9
86              count{tid="12170",cpu="3"} 107
87              count{tid="1802",cpu="0"} 33687
88              count{tid="12617",cpu="1"} 99
89              [...]
90
91
92

SAFETY AND SECURITY

94       See the stap(1) manual page for additional information  on  safety  and
95       security.
96
97

BUGS

103       Use  the  Bugzilla  link  of  the project web page or our mailing list.
104       http://sourceware.org/systemtap/, <systemtap@sourceware.org>.
105
106
107
108                                                                    STAPBPF(8)