Merge pull request #1782 from rundeck/fix-job-metrics-documentation

Include notes about missing system configs related to job metrics and roi summary plugins

Author: fdevans

docs/administration/configuration/config-file-reference.md

@@ -857,6 +857,32 @@ If the log file is larger than this value, the log viewer will display a "Whale
 
 The default value for this property is 3MB.
 
+### Execution daily metrics
+
+**Purpose:** Record per-day execution aggregates into scheduled execution stats as executions complete. That data backs the stats-based mode of the [execution metrics API](/api/index.md#execution-query-metrics) (`useStats=true`, API v57+), which avoids scanning the execution table and is intended for large environments.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `rundeck.executionDailyMetrics.enabled` | `false` | When `true`, daily metrics are updated when executions finish. Required for meaningful results when using `useStats=true` on the metrics API. |
+| `rundeck.feature.guiUseExecutionDailyMetrics.enabled` | `false` | When `true`, enables the `guiUseExecutionDailyMetrics` feature for the GUI so compatible views can use the stats-based metrics path. |
+
+**Collection window:** Metrics exist only for executions that complete after `rundeck.executionDailyMetrics.enabled` is turned on. Older executions are not backfilled into the daily aggregates.
+
+**Operational order:** Turn on `rundeck.executionDailyMetrics.enabled` first and allow executions to run so aggregates populate; then enable the GUI feature when your UI and plugins expect the stats-based flow.
+
+**Job Metrics UI plugin:** After you enable `rundeck.feature.guiUseExecutionDailyMetrics.enabled`, a Job Metrics UI plugin that still relies on the legacy metrics behavior may show all jobs as having no executions. That is expected until the plugin uses the updated stats-based API (`useStats=true`, API v57+).
+
+### Job Metrics and ROI Summary UI
+
+**Purpose:** Control visibility of the bundled Job Metrics and ROI Summary UI. These settings do not remove plugins from the installation; they stop the UI from loading those integrations.
+
+Set properties in `rundeck-config.properties`. Most deployments require a Rundeck restart for changes to take effect.
+
+| Property | Default | Description |
+|----------|---------|-------------|
+| `rundeck.plugin.jobmetrics.disabled` | `false` | When `true`, disables the Job Metrics UI. |
+| `rundeck.plugin.roisummary.disabled` | `false` | When `true`, disables the ROI Summary UI. |
+
 ### Metrics Capturing
 
 :::tip

docs/api/index.md

@@ -3918,6 +3918,10 @@ Paging parameters `max` and `offset` will have no effect on the result.
 * `begin` (string): When using `useStats=true`, filter metrics to include only executions that completed on or after this date. Format: `yyyy-MM-ddTHH:mm:ssZ` (ISO8601).
 * `end` (string): When using `useStats=true`, filter metrics to include only executions that completed on or before this date. Format: `yyyy-MM-ddTHH:mm:ssZ` (ISO8601).
 
+::: tip Stats-based mode requirements
+`useStats=true` reads pre-aggregated daily metrics written when executions complete. For this mode to return data, you must set `rundeck.executionDailyMetrics.enabled=true` in `rundeck-config.properties`, and metrics are only available from the time that property was enabled (no automatic backfill). Separately, the GUI feature flag `rundeck.feature.guiUseExecutionDailyMetrics.enabled` controls whether Web UI views (and any plugins that rely on those views) use stats-based metrics instead of querying executions directly; if the flag is enabled but daily metrics are disabled or not yet populated for a period, those stats-based views can show empty results. See [Execution daily metrics](/administration/configuration/config-file-reference.md#execution-daily-metrics).
+:::
+
 **Response**
 
 When `groupByJob` is not used, the response is an object with `duration` entry containing duration stats, and a `total` entry with total executions:

docs/developer/ui-plugins.md

@@ -70,7 +70,7 @@ Use Gradle with the Asset Pipeline plugin for production-quality plugins.
 See the [modern structure](#modern-plugin-structure-with-asset-pipeline) section below.
 
 **Example repositories using this approach:**
-- [ui-job-metrics](https://github.com/rundeck-plugins/ui-job-metrics) - Job execution metrics dashboard
+- [ui-job-metrics](https://github.com/rundeck-plugins/ui-job-metrics) - Job execution metrics dashboard (for stats-based metrics with `rundeck.feature.guiUseExecutionDailyMetrics.enabled`, plugins should use the [execution metrics API](/api/index.md#execution-query-metrics) with `useStats=true`, API v57+; see [Execution daily metrics](/administration/configuration/config-file-reference.md#execution-daily-metrics))
 - [ui-roi-summary](https://github.com/rundeck-plugins/ui-roi-summary) - ROI summary views
 
 ## Simple Plugin Structure (Manual)

docs/history/5_x/version-5.19.0.md

@@ -14,7 +14,7 @@ feed:
 
 ## Overview
 
-This release focuses on stability, performance, and security improvements across the platform. Key updates include enhanced AWS SSM execution timeouts (up to 12 hours), significant Job UI Metrics performance optimizations, and fixes for Ansible workflow output handling and Vault timestamp issues. Security updates address multiple CVEs in the Azure Storage plugin and Docker image dependencies.
+This release focuses on stability, performance, and security improvements across the platform. Key updates include enhanced AWS SSM execution timeouts (up to 12 hours), significant Job UI Metrics performance optimizations (these require enabling configuration flags; see the note under [Runbook Automation Updates](#runbook-automation-updates) and [Execution daily metrics](/administration/configuration/config-file-reference.md#execution-daily-metrics)), and fixes for Ansible workflow output handling and Vault timestamp issues. Security updates address multiple CVEs in the Azure Storage plugin and Docker image dependencies.
 
 <VidStack src="youtube/YXidHZOdR1M" poster="https://img.youtube.com/vi/YXidHZOdR1M/maxresdefault.jpg"/>
 
@@ -36,6 +36,12 @@ Bump aiohttp to 3.13.3 minimum for CVE-2025-69223, CVE-2025-69227, and CVE-2025-
 
 Significantly improved the performance of Job UI Metrics by introducing batch processing that fetches metrics for all jobs in a single API call instead of making individual requests for each job, reducing page load times from minutes to seconds in projects with many jobs and eliminating timeout issues caused by excessive database queries.
 
+::: tip Configuration required for the optimized path [Self Hosted]
+The faster Job Metrics experience uses pre-aggregated daily execution statistics and API v57+ stats-based metrics (`useStats=true`). To enable set **`rundeck.executionDailyMetrics.enabled=true`** so the server records those aggregates when executions complete, and **`rundeck.feature.guiUseExecutionDailyMetrics.enabled=true`** so the UI uses them. Metrics are available only for executions that finish after daily metrics collection is turned on (no automatic backfill). Full details, API notes, and plugin behavior are documented under [Execution daily metrics](/administration/configuration/config-file-reference.md#execution-daily-metrics).
+
+Note: This is already configured for all SaaS instances of Runbook Automation
+:::
+
 
 ## Rundeck Open Source Product Updates