Posit Chronicle

Workbench | Preview

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

What is Chronicle?

Posit Chronicle is a self-hosted observability service that collects session telemetry, audit events, and runtime metrics from Posit Workbench. It stores that data as Parquet files on a local or shared filesystem, where downstream tools can query it without depending on an external observability backend.

When chronicle-enabled=1, Workbench starts and stops the embedded posit-chronicle process along with the rest of the server, and writes Chronicle’s generated configuration to /var/lib/rstudio-server/chronicle.gcfg. By default, Chronicle writes Parquet data under the Workbench shared-storage tree (/var/lib/rstudio-server/shared-storage/chronicle), so load-balanced deployments that mount server-shared-storage-path over Network File System (NFS) get a shared Chronicle data directory without extra configuration.

What Chronicle collects

Chronicle gathers data from Workbench through three independent paths:

Chronicle collects runtime metrics once it is enabled. The other two paths each need configuration.

Configuration

To enable Chronicle, set the following in /etc/rstudio/rserver.conf and restart Workbench with rstudio-server restart:

/etc/rstudio/rserver.conf
metrics-enabled=1
chronicle-enabled=1

Chronicle requires metrics-enabled=1. Workbench will not start if chronicle-enabled=1 is set without metrics-enabled=1.

The following table lists the main Chronicle configuration options:

Config Option Description Possible Values Default Value
chronicle-enabled Whether to enable the embedded Chronicle observability service. 0 or 1 0
chronicle-storage-location Path Chronicle uses for its Parquet storage when LocalStorage is active. A filesystem path <server-shared-storage-path>/chronicle
chronicle-environment Value written to [Agent].Environment in the generated chronicle.gcfg. Surfaces as an environment label on emitted telemetry. A string label production

See the rserver.conf reference for the canonical descriptions of each option.

Forwarding audit events and logs over OTLP

Workbench exports audit events, session events, and logs over OTLP, and Chronicle runs a local OTLP receiver for them. Aggregate session counts and durations already arrive through the Prometheus scrape, so this path is what adds the per-session and audit event records. Pick an unused local port (for example, 5959) and use it on both sides.

In /etc/rstudio/rserver.conf, turn on OpenTelemetry log export and point it at that port:

/etc/rstudio/rserver.conf
otel-enabled=1
otel-logs-enabled=1
otel-logs-endpoint=http://localhost:5959/v1/logs

In chronicle-local.gcfg, set Chronicle’s receiver to the same port as a host:port address, without a scheme or path:

/etc/rstudio/chronicle-local.gcfg
[Workbench]
LogOTLPEndpoint = localhost:5959

Restart Workbench with rstudio-server restart. OpenTelemetry export requires the Monitoring license feature. See OpenTelemetry for the full set of export options and Overriding Chronicle configuration directly for how chronicle-local.gcfg works.

Collecting user information from the Workbench API

For Chronicle to collect user information, the admin-level Workbench API must be enabled. To enable it, set the following in /etc/rstudio/rserver.conf and restart Workbench with rstudio-server restart:

/etc/rstudio/rserver.conf
workbench-api-admin-enabled=1

Administering Chronicle with rstudio-server chronicle

Workbench exposes the Chronicle CLI through rstudio-server chronicle <args>.

The following commands show common uses:

Terminal
# Report the bundled Chronicle version
sudo rstudio-server chronicle version

# Report the running daemon's status.
sudo rstudio-server chronicle status

# Any other Chronicle subcommand (arguments are passed to Chronicle unmodified)
sudo rstudio-server chronicle --help

Overriding Chronicle configuration directly

Workbench rewrites /var/lib/rstudio-server/chronicle.gcfg on every rserver start, so hand-editing that file does not persist. The keys exposed through rserver.conf (chronicle-storage-location, chronicle-environment) are the supported way to influence the generated chronicle.gcfg for most deployments.

For configuration not exposed through rserver.conf (for example, tuning the Chronicle log verbosity), create a chronicle-local.gcfg file alongside the other Workbench configuration files. Chronicle loads this file after the generated chronicle.gcfg, so any key set here overrides the generated value.

/etc/rstudio/chronicle-local.gcfg
[Logging]
Level = debug

chronicle-local.gcfg lives in the Workbench configuration directory, which defaults to /etc/rstudio. (See Alternate configuration file location for information about changing the configuration directory.) Changes to chronicle-local.gcfg take effect after the next rstudio-server restart.

Migration from standalone Chronicle

Follow this checklist before enabling the embedded service on a host that already runs a standalone Chronicle deployment:

  1. Stop the standalone posit-chronicle service (for example, sudo systemctl stop posit-chronicle). rserver starts and stops the embedded service, so the two cannot run concurrently against the same data directory.
  2. Decide how to handle the existing Parquet data directory. If the standalone deployment wrote to a custom path, either copy it under <server-shared-storage-path>/chronicle or point chronicle-storage-location in rserver.conf at the existing path.
  3. Make the data directory writable by the Workbench service user. The embedded Chronicle runs as rstudio-server by default, so chown any carried-forward directory to rstudio-server:rstudio-server.
  4. Re-express anything you previously hand-edited in the standalone chronicle.gcfg (custom logging, agent overrides, or other settings not exposed through rserver.conf) in /etc/rstudio/chronicle-local.gcfg. See Overriding Chronicle configuration directly above. rserver rewrites the generated chronicle.gcfg on every start, so direct edits to that generated file do not persist.
  5. Uninstall the standalone Chronicle package so its binary, unit files, and /etc/rstudio/chronicle.gcfg do not drift away from what rserver manages.
  6. Set chronicle-enabled=1 in rserver.conf and restart Workbench.
  7. Confirm that pgrep posit-chronicle returns a single PID owned by the Workbench service user.
  8. Confirm that /var/lib/rstudio-server/chronicle.gcfg exists with mode 0640.
Back to top