What’s New in Chronicle

2025.05.0

Improvements

Expanded metrics

This release significantly expands the metrics collected and provided by Chronicle. In an effort to expose as much usage data available from the products as possible, Chronicle now includes the majority of the metrics currently available from the Connect and Workbench APIs and metrics endpoints.

A list of all collected data is available in the Chronicle Data section of the appendix.

Chronicle Metrics Cookbook

This release introduces a comprehensive metrics cookbook that serves both as documentation of all available metrics, and as a way to browse the actual data being collected.

The cookbook provides code snippets that can be used to assemble your own custom reporting or dashboards based on Chronicle data. Code can be modified to adjust to specific reporting needs, or joined with your own proprietary data for enhanced analysis.

To generate the cookbook with your own Chronicle data, you must have Quarto version 1.5.57 or later installed. See the Reports section for more details.

Breaking Changes

The following changes have been made since the previous release (2024.03.1):

Posit Usage Report

  • The previous Posit Usage Report has been replaced by the new Chronicle Metrics Cookbook. Data that was previously included in the usage report is now available from the corresponding metrics pages in the cookbook.

Chronicle Server

  • All previously collected metrics have been superseded by newer, more complete versions available under a /v2 directory in the data store. Data collected prior to upgrade in the /v1 directory will no longer be updated, but will remain available to previously deployed reports. After upgrade, all new data will be written to the /v2 directory.

Chronicle Agent

  • None

Known issues

The following data issues are known and will be addressed in a future release:

  • For metrics that use Delta Aggregation, any events that occur prior to Chronicle installation are not counted. This may cause a 0 value to appear in reports.

  • For aggregated metrics, when a metric value goes to 0, the previous value may still show in the Cookbook reports. For example:

    • If a Connect application is deleted, it may still appear in the Top Content table in Connect Content Visits report.

  • When a user is deleted or locked in Posit Workbench, the user may still be included in the list of Active Users and may still be counted in the number of Workbench Distinct Users.

  • When running in Kubernetes, OS Information in the build_info metrics reports the operating system for the agent container rather than the OS of the product container.

  • In the Cookbook Connect Users Report, the User Count Summary table does not count locked users. The other tables and plots on that Report do count locked users. This causes some inconsistent values (for example, the number of users shown on the User Growth Over Time graph may be larger than the number of users shown in the User Count Summary table.) The User Count Summary table is more relevant for actual license usage considerations.

Upgrades

For those upgrading from a previous release, please review the following upgrade notes based on your currently installed Chronicle version:

  • After upgrading Chronicle Server to 2025.05.0, newly collected data will be stored in the /v2 directory. Earlier data in the /v1 directory will not be updated, and can be safely removed if desired. Any previously deployed reports that reference the /v1 data should be updated to use /v2 metrics.
  • After upgrading Chronicle Agent on Posit Workbench servers running 2024.12.0 or later, you must configure an API key to allow Chronicle to read additional Workbench data and metrics. Perform the following steps on each Workbench server instance:
    1. Enable admin-level tokens and restart Posit Workbench.
    2. Follow the instructions to Configure Workbench API Key on the Chronicle agent.
  • After upgrading Chronicle on Red Hat-based systems, manually start the service with sudo systemctl start chronicle (and/or sudo systemctl start chronicle-agent).
  • When you set an Agent Environment Variable to override metric endpoint auto-detection, the agent will no longer fall back to auto-detection if the variable is invalid. If you encounter failures after the upgrade, verify and remove any outdated environment variables.
  • After upgrading Chronicle on Red Hat-based systems, manually start the service with sudo systemctl start chronicle (and/or sudo systemctl start chronicle-agent).
  • If you installed Chronicle Server or Agent using yum or apt, you may encounter errors due to a URL path change from rstudio to posit. Follow the Cloudsmith configuration instructions to update the repository path, or contact us for help.
  • If you override the Chronicle Agent’s autodetection of metrics endpoints by setting the CHRONICLE_CONNECT_METRICS_URL or CHRONICLE_WORKBENCH_METRICS_URL environment variables, you must now append /metrics to the end of the URL. Previously, /metrics was added automatically, but this change allows access through a reverse proxy or other URL rewriting.
  • Chronicle Server now stores temporary, internal data prior to compaction in a /private directory, instead of as temporary files in the primary /v1/metrics directory. After upgrading, any uncompacted data from the previous hour may be lost, causing a small gap in hourly data right before the upgrade. However, this should have minimal impact on overall metrics quality.

2025.03.1

Bug Fixes

Posit Usage Report

Fixed an issue where the Posit Usage Report lacked scrollbars for a long list of Workbench Active Users.

2025.03.0

Improvements

In addition to many bug fixes and stability improvements, this release of Chronicle expands our data and reporting in several key areas.

Posit Usage Report

Chronicle’s Posit Usage Report now populates additional information, including:

  • General:
    • Chronicle Server version
    • Date ranges added to all tables
  • Posit Workbench:
    • Count of distinct users (deduplicated by userid)
    • User lists
    • Total jobs launched
  • Posit Connect:
    • Count of distinct users (deduplicated by email)

To generate the report, see the Reports section.

Workbench API support

Chronicle now gathers additional data from the Workbench API. This requires Workbench 2024.12.0 or later and an API Key. If upgrading from an earlier release of Chronicle, see the upgrade notes below.

Data aggregation

Individual data metrics aggregate daily to eliminate duplication and reduce data volume, enabling easier reporting. Metrics are aggregated using selected approaches suitable for the type of data. This results in an up to 100x reduction in data size over the unaggregated data, with minimal loss of fidelity. Note that the original unaggregated data is currently preserved, but will be addressed by additional data management and cleanup features in an upcoming release.

The included Posit Usage Report is now based on the aggregated data, instead of the raw promoted data used previously. This results in significant performance improvements when generating the report from data stored in S3.

Improved diagnostics

Both the server and agent now have status commands (chronicle status and chronicle-agent status). These commands provide a quick diagnostic overview of the status of the process and can aid in identifying issues with your Chronicle configuration.

Breaking Changes

The following changes have been made since the previous release (2024.11.0):

Chronicle Server

  • In previous releases, data was stored under <chronicle-data-folder>/v1. With the introduction of aggregation the data can now be found unaggregated in <chronicle-data-folder>/hourly and aggregated in <chronicle-data-folder>/daily. When first starting Chronicle Server after upgrading, existing data will automatically be migrated to the new locations.

    Included reports have been updated to use the new locations, but any custom reports that point to the previous locations will need to be updated.

Chronicle Agent

  • Agent configuration is now file-based. Configuration by environment variables, used in earlier releases, is now deprecated and may be removed in a future release. Please migrate any configuration options to the new Agent Configuration gcfg file format to ensure compatibility for future upgrades.
  • Support for Posit Package Manager in Chronicle Agent is temporarily disabled. The related metrics are currently unused and will be added back with additional reporting in a future release. Do not install Chronicle Agent with Posit Package Manager at this time.

Known issues

The following data issues are known and will be addressed in a future release:

  • For metrics that use Delta Aggregation, any events that occur prior to Chronicle installation are not counted. This may cause a 0 value to appear in reports.

  • For aggregated metrics, when a metric value goes to 0, the previous value may still show in the Posit Team Usage report. For example:

    • If a Connect application is deleted, it will still appear in the Content Visits table with the last known count of visits.
    • If all Connect applications of a particular type (e.g. Shiny) are deleted, the content type will still display in the Deployed Content table with the last known count.

  • When a user is deleted or locked in Posit Workbench, the user may still be included in the list of Active Users and may still be counted in the number of Workbench Distinct Users.

Upgrades

For those upgrading from a previous release, please review the following upgrade notes based on your currently installed Chronicle version:

  • After upgrading Chronicle Agent on Posit Workbench servers running 2024.12.0 or later, you must configure an API key to allow Chronicle to read additional Workbench data and metrics. Perform the following steps on each Workbench server instance:
    1. Enable admin-level tokens and restart Posit Workbench.
    2. Follow the instructions to Configure Workbench API Key on the Chronicle agent.
  • After upgrading Chronicle on Red Hat-based systems, manually start the service with sudo systemctl start chronicle (and/or sudo systemctl start chronicle-agent).
  • When you set an Agent Environment Variable to override metric endpoint auto-detection, the agent will no longer fall back to auto-detection if the variable is invalid. If you encounter failures after the upgrade, verify and remove any outdated environment variables.
  • After upgrading Chronicle on Red Hat-based systems, manually start the service with sudo systemctl start chronicle (and/or sudo systemctl start chronicle-agent).
  • If you installed Chronicle Server or Agent using yum or apt, you may encounter errors due to a URL path change from rstudio to posit. Follow the Cloudsmith configuration instructions to update the repository path, or contact us for help.
  • If you override the Chronicle Agent’s autodetection of metrics endpoints by setting the CHRONICLE_CONNECT_METRICS_URL or CHRONICLE_WORKBENCH_METRICS_URL environment variables, you must now append /metrics to the end of the URL. Previously, /metrics was added automatically, but this change allows access through a reverse proxy or other URL rewriting.
  • Chronicle Server now stores temporary, internal data prior to compaction in a /private directory, instead of as temporary files in the primary /v1/metrics directory. After upgrading, any uncompacted data from the previous hour may be lost, causing a small gap in hourly data right before the upgrade. However, this should have minimal impact on overall metrics quality.

2024.11.0

Improvements

Posit Usage Report

This version of Chronicle updates the Posit Usage Report functionality to populate additional information, including:

Posit Connect

  • R and Python versions installed and configured
  • Content visits
  • Version information
  • User seats

Posit Workbench

  • Additional session launch metrics

Additionally, the report now explicitly notes elements that are not yet implemented, instead of leaving them with missing values.

See the Reports section for how to generate the report.

Diagnostics and logging

To help validate the successful installation of Chronicle and diagnose issues, the Agent and Server now include additional logging details.

Breaking

The following changes have been made since the previous release (2024.09.0):

  • The Chronicle documentation is now permanently available at docs.posit.co/chronicle. Please update any outdated bookmarks, as previous locations will no longer be updated.
  • Chronicle Agent:
    • The agent no longer collects or stores system-level host metrics and now focuses only on application metrics. These host metrics were not being used and contributed to higher data volume. We may reintroduce them in the future if they are needed.
    • Support for Posit Package Manager in Chronicle Agent is temporarily disabled. The related metrics are currently unused and will be added back with additional reporting in a future release. Do not install Chronicle Agent with Posit Package Manager at this time.

Known issues

Upgrades

For those upgrading from a previous release, please review the following upgrade notes based on your currently installed Chronicle version:

  • After upgrading Chronicle on RedHat-based systems, manually start the service with sudo systemctl start chronicle (and/or sudo systemctl start chronicle-agent).
  • When you set an Agent Environment Variable to override metric endpoint auto-detection, the agent will no longer fall back to auto-detection if the variable is invalid. If you encounter failures after the upgrade, verify and remove any outdated environment variables.
  • After upgrading Chronicle on RedHat-based systems, manually start the service with sudo systemctl start chronicle (and/or sudo systemctl start chronicle-agent).
  • If you installed Chronicle Server or Agent using yum or apt, you may encounter errors due to a URL path change from rstudio to posit. Follow the Cloudsmith configuration instructions to update the repository path, or contact us for help.
  • If you override the Chronicle Agent’s autodetection of metrics endpoints by setting the CHRONICLE_CONNECT_METRICS_URL or CHRONICLE_WORKBENCH_METRICS_URL environment variables, you must now append /metrics to the end of the URL. Previously, /metrics was added automatically, but this change allows access through a reverse proxy or other URL rewriting.
  • Chronicle Server now stores temporary, internal data prior to compaction in a /private directory, instead of as temporary files in the primary /v1/metrics directory. After upgrading, any uncompacted data from the previous hour may be lost, causing a small gap in hourly data right before the upgrade. However, this should have minimal impact on overall metrics quality.

Documentation

The Chronicle documentation is now permanently available at docs.posit.co/chronicle.

Installation and upgrade procedures:

Back to top