Chronicle

Posit Chronicle is a self-hosted observability service that collects runtime metrics from Posit Package Manager. 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 Chronicle documentation.

System requirements

Chronicle runs alongside Package Manager 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 packages, repositories, and download activity. Larger installations might require significantly more disk space.

The Package Manager installer creates the posit-chronicle system user and group automatically and adds the rstudio-pm user to the posit-chronicle group; no additional account setup is required.

Enabling Chronicle

Add the following to your Package Manager configuration file:

/etc/rstudio-pm/rstudio-pm.gcfg
[Chronicle]
Enabled = true

[Metrics]
Enabled = true
Listen = :2112

Prometheus metrics must be enabled for Chronicle to run. Chronicle scrapes runtime resource metrics from the /metrics endpoint, and does not start if Metrics.Enabled is not set to true.

Local storage is enabled by default. See Storage for storage options including S3.

Restart Package Manager for the change to take effect. Package Manager starts Chronicle as a managed subprocess.

Storage

Chronicle supports two storage backends: local filesystem and Amazon S3. Local storage is always enabled. You can optionally enable S3 storage in addition to local storage.

Local storage

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

/etc/rstudio-pm/rstudio-pm.gcfg
[Chronicle]
Enabled = true
StorageLocation = /var/lib/posit-chronicle/data

The StorageAccess 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). The installer automatically adds the rstudio-pm user to this group.
owner Only the Chronicle process can read the files.

Multi-node setups

In multi-node deployments, StorageLocation must point to shared storage (for example, NFS or Amazon EFS) so that all nodes write to the same location.

The installer creates the posit-chronicle user and group automatically, assigning the next available system UID and GID on each host. Chronicle runs as the rstudio-pm user (the same user as Package Manager) and writes files to the shared storage directory. The setgid bit on the data directory ensures that files inherit the posit-chronicle group ownership, allowing other Posit products (such as Connect) to access the same Chronicle data.

Shared storage such as NFS or EFS enforces permissions by numeric ID, so the posit-chronicle group’s GID must be identical on every node for Chronicle to read and write shared data across nodes.

The IDs might 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 GIDs differ, align them so that posit-chronicle has the same 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 GID alignment is required.

Kubernetes deployments

In a Kubernetes deployment, Package Manager runs a separate Chronicle process inside each Package Manager pod. Because every pod runs its own process, all pods must write to a single shared destination. Choose a storage backend based on where Package Manager 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 Package Manager pod can read and write.

When using local storage, provision a dedicated shared location for Chronicle data. Do not place it inside the Package Manager 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-pm/rstudio-pm.gcfg
[Chronicle]
Enabled = true
S3Enabled = true
S3Bucket = my-chronicle-bucket
S3Region = us-east-1

S3Bucket is required when S3 storage is enabled. You can optionally set S3Region to specify the AWS region, 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.

For S3-compatible storage backends, set S3Endpoint to the service endpoint URL. When set, Chronicle uses path-style addressing.

Environment labeling

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

/etc/rstudio-pm/rstudio-pm.gcfg
[Chronicle]
Enabled = true
Environment = production

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

Verifying Chronicle is running

Use the rspm chronicle subcommand to check Chronicle status:

Terminal
sudo rspm chronicle status

This command requires root privileges because it connects to the Chronicle management socket, which is only accessible to the rstudio-pm user that runs the Chronicle process.

This is equivalent to:

Terminal
sudo chronicle status --config /etc/rstudio-pm/chronicle/package-manager-chronicle.gcfg

Returns version, uptime, receivers being scraped, and storage status. If Chronicle is down:

Unable to connect to Chronicle server management service. Is the Chronicle server running?

Troubleshooting

Log files

Chronicle writes its logs to:

/var/log/rstudio/package-manager-chronicle/chronicle.log

Generated configuration

Package Manager writes a runtime configuration file for Chronicle at:

/etc/rstudio-pm/chronicle/package-manager-chronicle.gcfg

Package Manager generates this file automatically. 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
Disk usage scales with the number of packages, repositories, and download activity. 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.

Back to top