Skip to content

About

Example reports for Posit Chronicle

Resources

Stars

4 stars

Watchers

2 watching

Forks

Repository files navigation

Chronicle Reports

Note

For data collected by Chronicle v2026.1.0 or earlier, use v0.2.2 of these reports. To install using pak: pak::pak("posit-dev/chronicle-reports@v0.2.2").

Chronicle Reports is an R package that provides pre-built Shiny dashboards and data access tools for analyzing usage data from Posit Chronicle. Chronicle helps organizations understand their use of Posit Connect and Posit Workbench through comprehensive metrics on users, content, and activity patterns. See the Chronicle announcement for more details.

This package serves two primary use cases:

  • For IT admins: Deploy pre-built dashboards to Posit Connect with minimal configuration
  • For power users: Access Chronicle data programmatically to build custom analyses and reports

Quick Start

Install the package and explore using sample data:

# Install from GitHub
pak::pak("posit-dev/chronicle-reports")

# Get sample data path
sample_path <- chronicle.reports::chronicle_sample_data()

# Run the Connect dashboard
chronicle.reports::chronicle_run_app("connect", base_path = sample_path)

Installation

From GitHub

Install the stable release from the main branch:

# install.packages("pak")
pak::pak("posit-dev/chronicle-reports")

For contributors, the development version is available:

Important

The dev branch may contain unstable or experimental features. Use at your own risk.

pak::pak("posit-dev/chronicle-reports@dev")

Prerequisites

R Version: Requires R >= 4.2.0.

Package Manager (optional): If using Posit Package Manager, obtain an appropriate URL and configure your R environment for optimized package installation:

# Example configuration (adjust 'noble' to match your Linux distribution)
options(repos = c(
  CRAN = sprintf(
    "https://packagemanager.posit.co/cran/latest/bin/linux/noble-%s/%s",
    R.version["arch"],
    substr(getRversion(), 1, 3)
  )
))

Running Reports

Basic Usage

Discover which apps are available using chronicle_list_apps():

# With default data path (/var/lib/posit-chronicle/data)
chronicle.reports::chronicle_list_apps()

Run any report application using chronicle_run_app():

# With default data path (/var/lib/posit-chronicle/data)
chronicle.reports::chronicle_run_app("connect")

Data Source Options

Custom Filesystem Path

If your Chronicle data is in a non-default location:

chronicle.reports::chronicle_run_app(
  "connect",
  base_path = "/path/to/chronicle/data"
)

S3 Storage

For Chronicle data stored in S3:

chronicle.reports::chronicle_run_app(
  "connect",
  base_path = "s3://chronicle-bucket/optional-prefix"
)

Environment Variables

Set CHRONICLE_BASE_PATH to avoid the need to pass in the path every time:

Sys.setenv(CHRONICLE_BASE_PATH = "/path/to/chronicle/data")
chronicle.reports::chronicle_run_app("connect")

Set CHRONICLE_DATA_WINDOW to limit how many days of data the dashboards load on startup. This is useful for improving load times when you have a large amount of historical data:

# Only load the last 90 days of data on startup
Sys.setenv(CHRONICLE_DATA_WINDOW = 90)
chronicle.reports::chronicle_run_app("connect")

When unset all available data is loaded by default.

Available Reports

Chronicle Reports includes two comprehensive dashboards. List available reports at any time:

chronicle.reports::chronicle_list_apps()
# Returns: c("connect", "workbench")

Connect Dashboard

A multi-page dashboard for Posit Connect usage analysis with three main sections:

  • Users:
    • Overview: Total licensed users, daily active users, publishers with trend visualizations
    • User List: Searchable, filterable table of all users with role and activity details
  • Content:
    • Overview: Content metrics and trends
    • Content List: Searchable inventory of all published content
  • Usage:
    • Content Hits: Hit trends and patterns
    • Content Hits by User: Detailed view of content hits per user

Run it: chronicle_run_app("connect")

Connect Dashboard showing user overview, content metrics, and usage statistics

Workbench Dashboard

A multi-page dashboard for Posit Workbench user analytics:

  • Users:
    • Overview: Licensed users, daily active users, administrators, and super administrators with trend analysis
    • User List: Searchable, Filterable table showing all users with role and activity information
  • Sessions:
    • Overview: Sessions started over time by session type, plus startup-duration trends (median and P95) per session type, with date and environment filters; includes total session hours for the selected range
    • Duration: Median session-duration trend by session type and a sessions-by-exit-reason breakdown (one bar per session type, colored by exit reason), with date, environment, and session type filters
    • User Summary: One row per user (with usernames from the latest user list) and session counts pivoted by session type, with date range and environment filters, searchable by username or GUID
    • User Detail: Single-user drill-down with a searchable user selector (labeled by username), totals, a Gantt-style session timeline colored by session type, and a table of that user's sessions

Run it: chronicle_run_app("workbench")

Workbench Dashboard displaying user analytics and activity trends

Publishing to Posit Connect

Deploy Chronicle Reports dashboards to Posit Connect for organization-wide access.

Deploy directly from GitHub

The chronicle-reports repository includes manifest files for direct deployment from GitHub to Posit Connect. Refer to the Posit Connect documentation for detailed instructions.

You will need to define the CHRONICLE_BASE_PATH environment variable in Connect to point to your Chronicle data location. This may be set globally or per-application.

Create your own deployment

Alternatively, create a custom Shiny application and deploy it to Posit Connect.

Step 1: Create Project Directory

Create a directory with an app.R file:

mkdir chronicle-connect-report
cd chronicle-connect-report

Create app.R:

# app.R
chronicle.reports::chronicle_run_app(
  "connect",
  base_path = "/path/to/chronicle/data"
)

Step 2: Deploy to Connect

# install.packages("rsconnect")
rsconnect::deployApp(
  appDir = "chronicle-connect-report",
  appFiles = c("app.R")
)

Step 3: Configure Environment Variable (Recommended)

Instead of hard coding the path, configure it in the Posit Connect UI:

  1. Navigate to your deployed application in Connect
  2. Go to the "Vars" panel
  3. Add environment variable: CHRONICLE_BASE_PATH = /path/to/chronicle/data
  4. Optionally add CHRONICLE_DATA_WINDOW to limit how many days of data the dashboard loads (e.g., 90 for the last 90 days)

Then simplify your app.R:

# app.R
chronicle.reports::chronicle_run_app("connect")

Granting access to Chronicle data

The deployed content must be able to read the Chronicle data files on the Connect server. By default, Chronicle writes its data files with group-only permissions. Rather than loosening those permissions, a Connect admin can configure the content to run as a Unix account that belongs to the group that owns the Chronicle data.

Sample Data

Use chronicle_sample_data() to explore Chronicle Reports without access to real Chronicle data. This function creates a temporary directory with minimal sample metrics for both Connect and Workbench.

Sample data includes realistic user roles (viewers, publishers, administrators), environments (Production, Development, Staging), and usage data.

Using Sample Data

# Get path to sample data
sample_path <- chronicle.reports::chronicle_sample_data()

# List available metrics
chronicle.reports::chronicle_list_data(sample_path)

# Run an app with sample data
chronicle.reports::chronicle_run_app("connect", base_path = sample_path)

# Load and explore sample data
data <- chronicle.reports::chronicle_data("connect/user_totals", sample_path)
data |> dplyr::collect()

The sample data is cached per R session and automatically cleaned up. Use chronicle_sample_data(refresh = TRUE) to regenerate.

Data Access for Custom Analysis

Beyond pre-built dashboards, Chronicle Reports provides functions for accessing Chronicle data programmatically to build custom analyses and reports.

Curated Metrics (Recommended)

Use chronicle_data() to access curated metrics. These are pre-processed datasets optimized for common analyses:

# Load a curated metric
data <- chronicle.reports::chronicle_data(
  "connect/user_totals",
  base_path = "/path/to/chronicle/data"
)

# Works seamlessly with dplyr
library(dplyr)
data |>
  filter(date >= as.Date("2024-01-01")) |>
  collect()

List all available curated metrics:

chronicle.reports::chronicle_list_data(base_path = "/path/to/chronicle/data")

# Returns:
[1] "connect/content_list"
[2] "connect/content_totals"
[3] "connect/content_hits_totals"
[4] "connect/content_hits_totals_by_user"
[5] "connect/user_list"
[6] "connect/user_totals"
[7] "workbench/session_duration"
[8] "workbench/session_start_totals"
[9] "workbench/session_start_totals_by_user"
[10] "workbench/user_list"
[11] "workbench/user_totals"

Raw Metrics (Advanced)

Use chronicle_raw_data() for granular control over raw Chronicle metrics:

# Load raw daily metrics
data <- chronicle.reports::chronicle_raw_data(
  "connect_users",
  base_path = "/path/to/chronicle/data",
  frequency = "daily"
)

# Load specific date range
data <- chronicle.reports::chronicle_raw_data(
  "connect_users",
  base_path = "/path/to/chronicle/data",
  frequency = "daily",
  ymd = list(year = 2024, month = 1, day = 15)
)

List all available raw metrics:

chronicle.reports::chronicle_list_raw_data(
  base_path = "/path/to/chronicle/data",
  frequency = "daily"
)

Building Custom Reports

Power users can build custom reports by copying and modifying existing dashboards.

Copy Existing App as Template

# Copy an existing app as a starting point
file.copy(
  system.file("apps/connect", package = "chronicle.reports"),
  "my-custom-report",
  recursive = TRUE
)

# Modify the code in my-custom-report/app.R

# Test your custom app
shiny::runApp("my-custom-report")

License

MIT License. See LICENSE file for details.

About

Example reports for Posit Chronicle

Resources

Stars

4 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages