Chronicle

Warning

Chronicle is a preview feature. Its configuration, data formats, and behavior may change in future releases.

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

For a full description of the data Chronicle collects, including the curated data sets and their schemas, see the Posit Chronicle documentation.

System requirements

Chronicle runs alongside Connect on the same host. The recommended minimum resources are:

Resource	Minimum
CPU	1 core
Memory	1 GB RAM
Disk	15 GB

Disk usage scales with the number of content items, users, and visits. Larger installations may require significantly more disk space.

Connect’s installer creates the posit-chronicle system user and group automatically; no manual account setup is needed.

Enabling Chronicle

Add the following to your Connect configuration file:

/etc/rstudio-connect/rstudio-connect.gcfg

[Chronicle]
Enabled = true
LocalStorageEnabled = true

[Metrics]
PrometheusListen = ":3232"

Prometheus metrics must be enabled for Chronicle to run. Chronicle scrapes runtime resource metrics from Connect’s /metrics endpoint, and will not start if PrometheusListen is not set.

At least one storage backend must be configured. See Storage for S3 and local options. For richer data collection, see Enhanced data collection.

Restart Connect for the change to take effect. Connect will start Chronicle as a managed subprocess and automatically provision a service token for it.

Storage

Chronicle supports two storage backends: local filesystem and Amazon S3. At least one must be enabled. Both can be enabled simultaneously.

Local storage

Chronicle writes local data to /var/lib/posit-chronicle/data by default. Use LocalStorageLocation to customize the path.

/etc/rstudio-connect/rstudio-connect.gcfg

[Chronicle]
Enabled = true
LocalStorageEnabled = true

The LocalStorageAccess setting controls file permissions on the data directory:

Value	Description
all	Any user on the system can read the files
group	Only members of the posit-chronicle group can read the files (default).
owner	Only the Chronicle process can read the files.

Multi-node setups

In multi-node deployments, LocalStorageLocation must point to shared storage (for example, NFS or Amazon EFS) so that all nodes write to the same location. However, ConfigDir must remain a node-local path because each Connect replica runs its own Chronicle process.

The installer creates the posit-chronicle user and group automatically, assigning the next available system UID and GID on each host. As described in Consistent users and groups, shared storage such as NFS or EFS enforces permissions by numeric ID, so the posit-chronicle user’s UID and group’s GID must be identical on every node for Chronicle to read and write shared data across nodes.

The IDs may line up on their own, but they can diverge when hosts have different existing accounts. To check, compare the IDs reported on each node:

Terminal

id posit-chronicle

If the IDs differ, align them so that posit-chronicle has the same UID and GID across all nodes. To avoid the requirement entirely, use S3 storage instead of local storage. Chronicle never writes to the shared filesystem when using S3, so no UID/GID alignment is required.

Off-host execution (Kubernetes)

In an off-host execution (Kubernetes) deployment, Connect runs a separate Chronicle process inside each Connect pod. Because every pod runs its own process, all pods must write to a single shared destination. Choose a storage backend based on where Connect runs:

• On AWS: Use S3 storage. Each pod writes to the same bucket, so you do not need a shared volume.
• On other platforms: Use local storage backed by a shared filesystem that every Connect pod can read and write.

When using local storage, provision a dedicated shared location for Chronicle data. Do not place it inside the Connect data directory (Server.DataDir); the Chronicle data must be a separate location, even if it uses the same class of shared storage.

S3 storage

To write Parquet files to an S3 bucket:

/etc/rstudio-connect/rstudio-connect.gcfg

[Chronicle]
Enabled = true
S3StorageEnabled = true
S3Bucket = my-chronicle-bucket
S3Region = us-east-1

Both S3Bucket and S3Region are required when S3 storage is enabled. You can optionally set S3Prefix to organize files under a key prefix, and S3Profile to use a specific AWS credentials profile.

Chronicle uses the standard AWS credential chain. If S3Profile and S3Region are not set, Chronicle falls back to the AWS_PROFILE and AWS_REGION environment variables.

Enhanced data collection

Enabling OpenTelemetry gives Chronicle access to structured log events:

/etc/rstudio-connect/rstudio-connect.gcfg

[Chronicle]
Enabled = true

[OpenTelemetry]
Enabled = true

• OpenTelemetry — Structured log events are forwarded to Chronicle through the embedded OTel Collector.

Environment labeling

Use the Environment setting to tag data with a label identifying this deployment:

/etc/rstudio-connect/rstudio-connect.gcfg

[Chronicle]
Enabled = true
Environment = production

This label appears in Chronicle reports and can be used to filter or group data across multiple deployments (for example, separating production from staging).

Troubleshooting

Log files

Chronicle logs are written to:

/var/log/rstudio/connect-chronicle/chronicle.log

Generated configuration

Connect writes a runtime configuration file for Chronicle at:

/etc/rstudio-connect/chronicle/connect-chronicle.gcfg

This file is generated automatically by Connect. Do not edit it directly. Inspecting it can be useful for verifying that Chronicle is configured as expected.

Common issues

Chronicle fails to start

Check the Chronicle log file for errors. Common causes include insufficient permissions on the data directory or invalid S3 credentials.

Disk usage growing unexpectedly

Chronicle’s disk usage scales with the number of content items, users, and visits. Monitor the data directory and increase disk allocation as needed.

S3 access denied

Verify that the AWS credentials available to Chronicle have s3:PutObject, s3:GetObject, s3:ListBucket, and s3:DeleteObject permissions on the configured bucket and prefix.

Configuration reference

For the full list of [Chronicle] settings, see the configuration appendix.