{"id":34566261,"url":"https://github.com/posit-dev/chronicle-reports","last_synced_at":"2026-04-02T12:24:08.104Z","repository":{"id":326002306,"uuid":"1049975684","full_name":"posit-dev/chronicle-reports","owner":"posit-dev","description":"Example reports for Posit Chronicle","archived":false,"fork":false,"pushed_at":"2026-03-24T23:14:10.000Z","size":729,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-26T04:54:53.170Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/posit-dev.png","metadata":{"files":{"readme":"README.md","changelog":"NEWS.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-03T19:09:11.000Z","updated_at":"2026-03-16T17:31:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/posit-dev/chronicle-reports","commit_stats":null,"previous_names":["posit-dev/chronicle-reports"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/posit-dev/chronicle-reports","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchronicle-reports","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchronicle-reports/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchronicle-reports/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchronicle-reports/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/posit-dev","download_url":"https://codeload.github.com/posit-dev/chronicle-reports/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posit-dev%2Fchronicle-reports/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31306024,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T09:48:21.550Z","status":"ssl_error","status_checked_at":"2026-04-02T09:48:19.196Z","response_time":89,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T09:05:58.181Z","updated_at":"2026-04-02T12:24:08.077Z","avatar_url":"https://github.com/posit-dev.png","language":"R","readme":"# Chronicle Reports\n\nChronicle 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](https://posit.co/blog/chronicle-product-announcement-aug-2025/) for more details.\n\nThis package serves two primary use cases:\n- **For IT admins**: Deploy pre-built dashboards to Posit Connect with minimal configuration\n- **For power users**: Access Chronicle data programmatically to build custom analyses and reports\n\n## Quick Start\n\nInstall the package and explore using sample data:\n\n```r\n# Install from GitHub\npak::pak(\"posit-dev/chronicle-reports\")\n\n# Get sample data path\nsample_path \u003c- chronicle.reports::chronicle_sample_data()\n\n# Run the Connect dashboard\nchronicle.reports::chronicle_run_app(\"connect\", base_path = sample_path)\n```\n\n## Installation\n\n### From GitHub\n\nInstall the stable release from the main branch:\n\n```r\n# install.packages(\"pak\")\npak::pak(\"posit-dev/chronicle-reports\")\n```\n\nFor contributors, the development version is available:\n\n\u003e [!IMPORTANT]\n\u003e The `dev` branch may contain unstable or experimental features. Use at your own risk.\n\n```r\npak::pak(\"posit-dev/chronicle-reports@dev\")\n```\n\n### Prerequisites\n\n**R Version**: Requires R \u003e= 4.1.0. The package supports the latest release version of R, as well as the previous four minor release versions. For example, if the latest release R version is 4.5, then versions 4.5, 4.4, 4.3, 4.2, and 4.1 are supported.\n\n**Package Manager (optional)**: If using Posit Package Manager, [obtain an appropriate URL](https://docs.posit.co/rspm/user/get-repo-url.html) and [configure your R environment](https://docs.posit.co/rspm/user/configure-r.html) for optimized package installation:\n\n```r\n# Example configuration (adjust 'noble' to match your Linux distribution)\noptions(repos = c(\n  CRAN = sprintf(\n    \"https://packagemanager.posit.co/cran/latest/bin/linux/noble-%s/%s\",\n    R.version[\"arch\"],\n    substr(getRversion(), 1, 3)\n  )\n))\n```\n\n## Running Reports\n\n### Basic Usage\n\n\nDiscover which apps are available using `chronicle_list_apps()`:\n\n```r\n# With default data path (/var/lib/posit-chronicle/data)\nchronicle.reports::chronicle_list_apps()\n```\n\nRun any report application using `chronicle_run_app()`:\n\n```r\n# With default data path (/var/lib/posit-chronicle/data)\nchronicle.reports::chronicle_run_app(\"connect\")\n```\n\n### Data Source Options\n\n#### Custom Filesystem Path\n\nIf your Chronicle data is in a non-default location:\n\n```r\nchronicle.reports::chronicle_run_app(\n  \"connect\",\n  base_path = \"/path/to/chronicle/data\"\n)\n```\n\n#### S3 Storage\n\nFor Chronicle data stored in S3:\n\n```r\nchronicle.reports::chronicle_run_app(\n  \"connect\",\n  base_path = \"s3://chronicle-bucket/optional-prefix\"\n)\n```\n\n#### Environment Variables\n\nSet `CHRONICLE_BASE_PATH` to avoid the need to pass in the path every time:\n\n```r\nSys.setenv(CHRONICLE_BASE_PATH = \"/path/to/chronicle/data\")\nchronicle.reports::chronicle_run_app(\"connect\")\n```\n\nSet `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:\n\n```r\n# Only load the last 90 days of data on startup\nSys.setenv(CHRONICLE_DATA_WINDOW = 90)\nchronicle.reports::chronicle_run_app(\"connect\")\n```\n\nWhen unset all available data is loaded by default.\n\n## Available Reports\n\nChronicle Reports includes two comprehensive dashboards. List available reports at any time:\n\n```r\nchronicle.reports::chronicle_list_apps()\n# Returns: c(\"connect\", \"workbench\")\n```\n\n### Connect Dashboard\n\nA multi-page dashboard for Posit Connect usage analysis with three main sections:\n\n- **Users**:\n  - Overview: Total licensed users, daily active users, publishers with trend visualizations\n  - User List: Searchable, filterable table of all users with role and activity details\n- **Content**:\n  - Overview: Content metrics and trends\n  - Content List: Searchable inventory of all published content\n- **Usage**:\n  - Overview: Visit trends and patterns\n  - Shiny Apps: Overall usage trends and a breakdown of usage by app\n  - Content Visits by User: Detailed view of content visits per user\n  - Shiny Sessions by User: Detailed view of Shiny app sessions per user\n\nRun it: `chronicle_run_app(\"connect\")`\n\n\u003cimg width=\"2509\" height=\"1296\" alt=\"Connect Dashboard showing user overview, content metrics, and usage statistics\" src=\"https://github.com/user-attachments/assets/9a9726ea-22e0-44a5-ae1c-c5a0ea1f1ffa\" /\u003e\n\n\n### Workbench Dashboard\n\nA multi-page dashboard for Posit Workbench user analytics:\n\n- **Users**:\n  - Overview: Licensed users, daily active users, administrators, and super administrators with trend analysis\n  - User List: Searchable, Filterable table showing all users with role and activity information\n\nRun it: `chronicle_run_app(\"workbench\")`\n\n\u003cimg width=\"2005\" height=\"1236\" alt=\"Workbench Dashboard displaying user analytics and activity trends\" src=\"https://github.com/user-attachments/assets/072e6dd7-f2a4-444f-ac2b-87f9382a3709\" /\u003e\n\n\n## Publishing to Posit Connect\n\nDeploy Chronicle Reports dashboards to Posit Connect for organization-wide access.\n\n### Deploy directly from GitHub\n\nThe chronicle-reports repository includes manifest files for direct deployment from GitHub to Posit Connect. Refer to the [Posit Connect documentation](https://docs.posit.co/connect/user/git-backed) for detailed instructions.\n\nYou will need to define the `CHRONICLE_BASE_PATH` environment variable in Connect to point to your Chronicle data location. This may be set [globally](https://docs.posit.co/connect/admin/process-management/#example-environment-variables) or [per-application](https://docs.posit.co/connect/user/content-settings/#content-vars).\n\n\n### Create your own deployment\n\nAlternatively, create a custom Shiny application and deploy it to Posit Connect.\n\n#### Step 1: Create Project Directory\n\nCreate a directory with an `app.R` file:\n\n```bash\nmkdir chronicle-connect-report\ncd chronicle-connect-report\n```\n\nCreate `app.R`:\n\n```r\n# app.R\nchronicle.reports::chronicle_run_app(\n  \"connect\",\n  base_path = \"/path/to/chronicle/data\"\n)\n```\n\n#### Step 2: Deploy to Connect\n\n```r\n# install.packages(\"rsconnect\")\nrsconnect::deployApp(\n  appDir = \"chronicle-connect-report\",\n  appFiles = c(\"app.R\")\n)\n```\n\n#### Step 3: Configure Environment Variable (Recommended)\n\nInstead of hard coding the path, configure it in the Posit Connect UI:\n\n1. Navigate to your deployed application in Connect\n2. Go to the \"Vars\" panel\n3. Add environment variable: `CHRONICLE_BASE_PATH = /path/to/chronicle/data`\n4. Optionally add `CHRONICLE_DATA_WINDOW` to limit how many days of data the dashboard loads (e.g., `90` for the last 90 days)\n\nThen simplify your `app.R`:\n\n```r\n# app.R\nchronicle.reports::chronicle_run_app(\"connect\")\n```\n\n## Sample Data\n\nUse `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.\n\nSample data includes realistic user roles (viewers, publishers, administrators), environments (Production, Development, Staging), and usage data.\n\n### Using Sample Data\n\n```r\n# Get path to sample data\nsample_path \u003c- chronicle.reports::chronicle_sample_data()\n\n# List available metrics\nchronicle.reports::chronicle_list_data(sample_path)\n\n# Run an app with sample data\nchronicle.reports::chronicle_run_app(\"connect\", base_path = sample_path)\n\n# Load and explore sample data\ndata \u003c- chronicle.reports::chronicle_data(\"connect/user_totals\", sample_path)\ndata |\u003e dplyr::collect()\n```\n\nThe sample data is cached per R session and automatically cleaned up. Use `chronicle_sample_data(refresh = TRUE)` to regenerate.\n\n## Data Access for Custom Analysis\n\nBeyond pre-built dashboards, Chronicle Reports provides functions for accessing Chronicle data programmatically to build custom analyses and reports.\n\n### Curated Metrics (Recommended)\n\nUse `chronicle_data()` to access curated metrics. These are pre-processed datasets optimized for common analyses:\n\n```r\n# Load a curated metric\ndata \u003c- chronicle.reports::chronicle_data(\n  \"connect/user_totals\",\n  base_path = \"/path/to/chronicle/data\"\n)\n\n# Works seamlessly with dplyr\nlibrary(dplyr)\ndata |\u003e\n  filter(date \u003e= as.Date(\"2024-01-01\")) |\u003e\n  collect()\n```\n\nList all available curated metrics:\n\n```r\nchronicle.reports::chronicle_list_data(base_path = \"/path/to/chronicle/data\")\n\n# Returns:\n[1] \"connect/content_list\"\n[2] \"connect/content_totals\"\n[3] \"connect/content_visits_totals_by_user\"\n[4] \"connect/shiny_usage_totals_by_user\"\n[5] \"connect/user_list\"\n[6] \"connect/user_totals\"\n[7] \"workbench/user_list\"\n[8] \"workbench/user_totals\"\n```\n\n### Raw Metrics (Advanced)\n\nUse `chronicle_raw_data()` for granular control over raw Chronicle metrics:\n\n```r\n# Load raw daily metrics\ndata \u003c- chronicle.reports::chronicle_raw_data(\n  \"connect_users\",\n  base_path = \"/path/to/chronicle/data\",\n  frequency = \"daily\"\n)\n\n# Load specific date range\ndata \u003c- chronicle.reports::chronicle_raw_data(\n  \"connect_users\",\n  base_path = \"/path/to/chronicle/data\",\n  frequency = \"daily\",\n  ymd = list(year = 2024, month = 1, day = 15)\n)\n```\n\nList all available raw metrics:\n\n```r\nchronicle.reports::chronicle_list_raw_data(\n  base_path = \"/path/to/chronicle/data\",\n  frequency = \"daily\"\n)\n```\n\n## Building Custom Reports\n\nPower users can build custom reports by copying and modifying existing dashboards.\n\n### Copy Existing App as Template\n\n```r\n# Copy an existing app as a starting point\nfile.copy(\n  system.file(\"apps/connect\", package = \"chronicle.reports\"),\n  \"my-custom-report\",\n  recursive = TRUE\n)\n\n# Modify the code in my-custom-report/app.R\n\n# Test your custom app\nshiny::runApp(\"my-custom-report\")\n```\n\n## License\n\nMIT License. See LICENSE file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposit-dev%2Fchronicle-reports","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposit-dev%2Fchronicle-reports","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposit-dev%2Fchronicle-reports/lists"}