Prometheus Metrics

Workbench | Enhanced Advanced

Prometheus Metrics

Preview feature

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 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:

  1. Http metrics describing the rserver process’s proxy request traffic.
  2. IDE Session metrics describing session events starting RStudio, Positron, VS Code, and Jupyter.
  3. Workbench Job metrics describing jobs launched from IDE sessions.
  4. 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 with rstudio-server restart). An example counter is the metric pwb_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
Back to top