docs: Address additional PR #7929 review feedback

- Move metrics overview into Prometheus section for better flow
- Add explicit /metrics path mention in Prometheus intro
- Add links to Status API and Decision Logs documentation
- Fix CLI tools to include proper documentation links
- Clarify which metrics are enabled with instrument=true parameter
- Remove inaccurate 'subset' terminology for Status API

Addresses review comments from charlieegan3 on September 25, 2025

Signed-off-by: Anivar A Aravind <[email protected]>

Author: anivar

docs/docs/monitoring.md

@@ -20,10 +20,17 @@ for all OpenTelemetry-related configurables.
 
 ## Prometheus
 
-OPA exposes an HTTP endpoint that can be used to collect performance metrics
+OPA exposes an HTTP endpoint at `/metrics` that can be used to collect performance metrics
 for all API calls. The Prometheus endpoint is enabled by default when you run
 OPA as a server.
 
+OPA provides two ways to access performance metrics:
+
+1. **System-wide metrics** via the `/metrics` Prometheus endpoint - Instance-level metrics across all OPA operations
+2. **Per-query metrics** via API responses with `?metrics=true` - Metrics for individual query executions
+
+These serve different purposes: system metrics for OPA instance monitoring and alerting, per-query metrics for debugging and optimization.
+
 You can enable metric collection from OPA with the following `prometheus.yml` config:
 
 ```yaml
@@ -86,21 +93,9 @@ When Prometheus is enabled in the status plugin (see [Configuration](./configura
 | last_success_bundle_request    | gauge       | Last successful bundle request in UNIX nanoseconds.    | STABLE |
 | bundle_loading_duration_ns     | histogram   | A histogram of duration for bundle loading.            | STABLE |
 
-## Metrics Overview
-
-OPA provides two ways to access performance metrics:
-
-1. **System-wide metrics** via the `/metrics` Prometheus endpoint - Instance-level metrics across all OPA operations
-2. **Per-query metrics** via API responses with `?metrics=true` - Metrics for individual query executions
-
-These serve different purposes: system metrics for OPA instance monitoring and alerting, per-query metrics for debugging and optimization.
-
-
-## Accessing Metrics
-
-### System-Wide Metrics (Prometheus Endpoint)
+## Available Metrics
 
-Access instance-level metrics across all OPA operations:
+The Prometheus `/metrics` endpoint exposes the following instance-level metrics:
 
 - **URL**: `http://localhost:8181/metrics` (default configuration)
 - **Method**: HTTP GET
@@ -112,9 +107,9 @@ Access instance-level metrics across all OPA operations:
 
 - **Per-query metrics**: See [REST API Performance Metrics](./rest-api#performance-metrics) for debugging individual queries
 - **Policy performance**: See [Policy Performance](./policy-performance#performance-metrics) for optimization guidance
-- **Status API**: Includes subset of metrics in status reports
-- **Decision logs**: Can include request-level metrics when configured
-- **CLI tools**: `opa eval --metrics` and `opa bench --metrics`
+- **Status API**: See [Status API](./management-status) for metrics reporting via status updates
+- **Decision logs**: See [Decision Logs](./management-decision-logs) for including metrics in decision logs
+- **CLI tools**: See [opa eval](./cli#eval) and [opa bench](./cli#bench) for command-line metric collection
 
 ## Health Checks
 

docs/docs/rest-api.md

@@ -2277,7 +2277,13 @@ OPA provides the following query performance metrics:
 - **timer_server_handler_ns**: time taken (in nanoseconds) to handle the API request.
 - **counter_server_query_cache_hit**: number of cache hits for the query.
 
-When query instrumentation is enabled (`instrument=true`), additional evaluation metrics are included. See [Policy Performance](./policy-performance#performance-metrics) for details on interpreting these metrics.
+When query instrumentation is enabled (`instrument=true`), the following additional detailed evaluation metrics are included:
+- **timer_eval_op_***: Various evaluation operation timers (e.g., `timer_eval_op_plug_ns`, `timer_eval_op_resolve_ns`)
+- **histogram_eval_op_***: Histograms tracking evaluation operation time distributions
+- **timer_rego_builtin_***: Built-in function execution times
+- **counter_rego_builtin_***: Built-in function call counts and cache hits
+
+See [Policy Performance](./policy-performance#performance-metrics) for details on interpreting these metrics.
 
 The `counter_server_query_cache_hit` counter gives an indication about whether OPA creates a new Rego query
 or it uses a pre-processed query which holds some prepared state to serve the API request. A pre-processed query will be