Prometheus Metrics
Prometheus Metrics
This feature is in preview. Preview features are unsupported and may face breaking changes in a future release. Any issues found in the feature will be addressed during the regular release schedule; they will not result in immediate patches or hotfixes.
We encourage customers to try these features and we welcome any feedback via Posit Support, but we recommend that the feature not be used in production until it is in general availability (i.e., officially released as a full feature). To provide feedback, please email your Posit Customer Success representative or sales@posit.co and specify that you are trialing this feature.
Posit Workbench can be configured to emit Prometheus metrics to a metric-specific endpoint. When enabled, the Prometheus metrics is served from a different port than the rest of Workbench to enable an administrator to configure different access control to the Prometheus metrics at the network level.
Configuration
To enable Prometheus metrics, set metrics-enabled=1
in rserver.conf
and then restart Workbench with rstudio-server restart
. By default, the /metrics
endpoint is available at the configured www-address
and port 8989
. For example, with the configuration below, metrics could be retrieved from https://my.example.workbench.org:8989/metrics
:
# /etc/rstudio/rserver.conf
www-address=my.example.workbench.org
ssl-enabled=1
#...
metrics-enabled=1
Below is the full set of configuration options:
Config Option | Description | Possible Values | Default Value |
---|---|---|---|
metrics-enabled | Whether or not to enable Prometheus metrics endpoint. | 0 or 1 | 0 |
metrics-port | The port to use for the Prometheus metrics endpoint. | Any valid Posix port that is not already in use, usually from 1024 - 65535 | 8989 |
metrics-address | The address to use for the prometheus metrics endpoint. When not present, the value of www-address is used, and TLS will be determined using ssl-enabled. When present, TLS will be inferred from the HTTP(S) scheme provided. If no HTTP(S) scheme is provided, HTTP will be used. | A valid network address. | The value of www-address |
It is strongly recommended to use the above settings to control how Prometheus metrics are exposed by Workbench. However, if more advanced control is needed, a custom NGNIX directive block can be provided by editing the /etc/rstudio/nginx.metrics-directives.conf
file. The location of this file can by modified with XDG_CONFIG_DIRS
or RSTUDIO_CONFIG_DIR
, as with other configuration files, or it can be set explicitly by adding server-nginx-metrics-directives-path=/path/to/desired/file.conf
to rserver.conf
. When this file is used, metrics-port
and metrics-address
will be ignored. Additionally, TLS must be explicitly included in the server directive block. When this file is used, it is not possible to configure Workbench to supply metrics directly from <www-address>/metrics
.
To use this file, a server
directive containing the location at which the metrics
information should be served. Below is an example where the directive has been modified so that the Prometheus metrics can be accessed directly from http://127.0.0.1
:
# /etc/rstudio/nginx.metrics-directives.conf
server {
listen 127.0.0.1:80;
location = / {
proxy_pass http://unix:/var/run/rstudio-server/rstudio-rserver/rserver.socket:/metrics/;
proxy_set_header Host $http_host;
add_header Strict-Transport-Security "max-age=86400";
proxy_redirect http://unix:/var/run/rstudio-server/rstudio-rserver/rserver.socket:/metrics/ $scheme://$host:80/;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 20d;
}
}
Metric Data
Workbench emits a variety of metrics to help understand the state of the system. The metrics are broken into four groups:
- Http metrics describing the
rserver
process’s proxy request traffic. - IDE Session metrics describing session events starting RStudio, Positron, VS Code, and Jupyter.
- Workbench Job metrics describing jobs launched from IDE sessions.
- System information.
There are three types of prometheus metrics used by workbench: counters, histograms, and gauges. Here’s a brief definition of each type:
- Counter
-
This metric maintains a steadily increasing count. It is reset each time the
rserver
process is restarted (typically withrstudio-server restart
). An example counter is the metricpwb_sessions_launched_total
. - Histogram
-
Maintains a set of buckets, each of which provided ascending threshold values. The histogram counts the number of samples below each threshold value for each bucket. An example histogram metric is:
pwb_session_startup_duration_seconds
. As with Counters, the counts are reset when the rstudio-server service is restarted. - Gauge
-
Provides the current value of a given metric for each sample. An example gauge metric is
pwb_sessions
.
Each metric may have labels attached to it, allowing the metric data to be queried by each label. For example, session metrics have a type
label that specified the name of the IDE used: rstudio-pro
, vscode
, jupyter
, or positron
. When labels are attached to a metric, the metric value is maintained for each combination of values for each label.
IDE Session Metrics
Metric | Type | Description | Labels |
---|---|---|---|
pwb_sessions_launched_total |
Counter | Cumulative IDE sessions launched from this server. | type |
pwb_sessions_failed_total |
Counter | Binary requests, by distro. | type |
pwb_session_startup_duration_seconds |
Histogram | Duration in seconds for session starts. | type |
pwb_session_startup_and_connect_duration_seconds |
Histogram | Duration of the start including time to join. | type |
pwb_session_duration_seconds |
Histogram | Total duration of session. | type |
pwb_sessions |
Gauge | Count of active workbench sessions by status. | cluster , type , status |
pwb_last_active_session_time |
Gauge | Timestamp of the last active Workbench session. |
Job Metrics
Metric | Type | Description | Labels |
---|---|---|---|
pwb_jobs_launched_total |
Counter | Cumulative Workbench jobs launched from this server. |
Http Metrics
Metric | Type | Description | Labels |
---|---|---|---|
pwb_http_requests_inflight |
Gauge | Number of HTTP requests in progress. | |
pwb_http_handlers_inflight |
Gauge | Number of HTTP requests active on a thread. | |
http_response_size_bytes_total |
Counter | Size of all HTTP responses from this server. | code , method , uri |
http_requests_total |
Counter | Number of HTTP requests served. | code , method , uri |
System Metrics
Metric | Type | Description | Labels |
---|---|---|---|
pwb_build_info |
Gauge | Workbench version, release name, and metrics version | |
pwb_active_user_sessions |
Gauge | Current number of active user logins on this server. | |
pwb_license_active_users |
Gauge | Number of registered users in the database, used for licensing. |
Metrics Details
Normally the /metrics
URL is requested by a prometheus server, but you can also load this URL into a web browser to see what information is being collected.
For each metric, there is a # HELP
comment and a # TYPE
comment in the metrics output. Below is an example of what some metrics may look like:
# HELP pwb_http_requests_total Total HTTP requests served.
# TYPE pwb_http_requests_total counter
pwb_http_requests_total{code="200",method="GET",uri="/metrics"} 4
pwb_http_requests_total{code="200",method="POST",uri="/log"} 2
pwb_http_requests_total{code="200",method="POST",uri="/events"} 225
pwb_http_requests_total{code="200",method="POST",uri="/rpc"} 413
# HELP pwb_license_active_users Named users actually consuming the user seats available under this node's product license.
# TYPE pwb_license_active_users gauge
pwb_license_active_users 3