# stap-exporter

## NAME



           stap-exporter - systemtap-prometheus interoperation mechanism
    


## SYNOPSIS



           **stap-exporter**[ _OPTIONS_ ]
    


## DESCRIPTION



           _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.
    


## OPTIONS



           The _stap-exporter_ program supports the following options.
    
           **-p --port PORT**
                  Listen to the specified TCP port for HTTP requests. Port
                  9900 is used by default.
    
           **-k --keepalive KEEPALIVE**
                  Scripts that run longer than KEEPALIVE seconds beyond the
                  last request are 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.
    


## 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.
    
                  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_ privi‐
           leges, 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 direc‐
           tory, to collect this data into a monitoring system.
    


## SAFETY AND SECURITY



           The stap-exporter server does not enforce any particular security
           mechanisms.  Therefore, deployment in an untrusted environment
           needs to consider:
    
           script selection
                  Since systemtap scripts are run under the privileges of the
                  stap-exporter process (probably _root_), the system adminis‐
                  trator 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 trust‐
                  ed 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.
    


## BUGS



           Use the Bugzilla link of the project web page or our mailing list.
           **http://sourceware.org/systemtap/ **, **< systemtap@sourceware.org>**.
    
           error::reporting(7stap),
           **https://sourceware.org/systemtap/wiki/HowToReportBugs **
    


* * *