docs: Focus metrics documentation on specific builtins per review

Following final review guidance to document only builtin-specific metrics
in their respective reference pages.

Changes:
- http.mdx: Document http.send timer and cache metrics
- regex.mdx: Document regex cache hit metric
- glob.mdx: Document glob cache hit metric
- rest-api.md: Clarify available instrumentation metrics

Removed broader metrics documentation from monitoring.md and
policy-performance.md per reviewer request to keep changes focused.

Fixes #6730

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

Author: anivar

docs/docs/policy-reference/builtins/glob.mdx

@@ -27,3 +27,13 @@ The following table shows examples of how `glob.match` works:
 | `output := glob.match("{cat,bat,[fr]at}", [], "bat")`            | `true`   | A glob with pattern-alternatives matchers.    |
 | `output := glob.match("{cat,bat,[fr]at}", [], "rat")`            | `true`   | A glob with pattern-alternatives matchers.    |
 | `output := glob.match("{cat,bat,[fr]at}", [], "at")`             | `false`  | A glob with pattern-alternatives matchers.    |
+
+## Performance Metrics
+
+When OPA is configured with metrics enabled, `glob.match` operations expose the following metrics in per-query metrics (accessible when `?metrics=true` is specified in API requests):
+
+| Metric | Description |
+| ------ | ----------- |
+| `counter_rego_builtin_glob_interquery_value_cache_hits` | Number of inter-query cache hits for compiled glob patterns |
+
+Effective glob pattern caching improves performance when the same patterns are used repeatedly across queries. High cache hit ratios indicate that glob compilation overhead is being minimized through caching.

docs/docs/policy-reference/builtins/http.mdx

@@ -113,3 +113,15 @@ The table below shows examples of calling `http.send`:
 | Files containing TLS material                 | `http.send({"method": "get", "url": "https://127.0.0.1:65331", "tls_ca_cert_file": "testdata/ca.pem", "tls_client_cert_file": "testdata/client-cert.pem", "tls_client_key_file": "testdata/client-key.pem"})`     |
 | Environment variables containing TLS material | `http.send({"method": "get", "url": "https://127.0.0.1:65360", "tls_ca_cert_env_variable": "CLIENT_CA_ENV", "tls_client_cert_env_variable": "CLIENT_CERT_ENV", "tls_client_key_env_variable": "CLIENT_KEY_ENV"})` |
 | Unix Socket URL Format                        | `http.send({"method": "get", "url": "unix://localhost/?socket=%F2path%F2file.socket"})`                                                                                                                           |
+
+## Performance Metrics
+
+When OPA is configured with metrics enabled, `http.send` operations expose the following metrics in per-query metrics (accessible when `?metrics=true` is specified in API requests):
+
+| Metric | Description |
+| ------ | ----------- |
+| `timer_rego_builtin_http_send_ns` | Total time spent in `http.send` calls during query evaluation |
+| `counter_rego_builtin_http_send_interquery_cache_hits` | Number of inter-query cache hits for `http.send` requests |
+| `counter_rego_builtin_http_send_network_requests` | Number of actual network requests made by `http.send` |
+
+High cache hit ratios indicate effective caching and reduced network overhead. These metrics help identify I/O bottlenecks in policies that make external HTTP requests.

docs/docs/policy-reference/builtins/regex.mdx

@@ -110,3 +110,13 @@ overlap. This can be useful when using patterns to define permissions or access
 rules. The function returns `true` if the two patterns overlap and `false` otherwise.
 
 <PlaygroundExample dir={require.context('../_examples/regex/globs_match/role_patterns')} />
+
+## Performance Metrics
+
+When OPA is configured with metrics enabled, regex operations expose the following metrics in per-query metrics (accessible when `?metrics=true` is specified in API requests):
+
+| Metric | Description |
+| ------ | ----------- |
+| `counter_rego_builtin_regex_interquery_value_cache_hits` | Number of regex cache hits for compiled patterns |
+
+Effective regex caching improves performance when the same patterns are used repeatedly. High cache hit ratios indicate that regex compilation overhead is being minimized through caching.

docs/docs/rest-api.md

@@ -2311,28 +2311,17 @@ Content-Type: application/json
 }
 ```
 
-> **Note**: These are per-query metrics returned inline with API responses. For system-wide instance metrics, see the `/metrics` Prometheus endpoint described in [Monitoring](./monitoring#prometheus).
+OPA currently supports the following query performance metrics:
 
-OPA provides the following query performance metrics:
-
-### Core Query Metrics
 - **timer_rego_input_parse_ns**: time taken (in nanoseconds) to parse the input
 - **timer_rego_query_parse_ns**: time taken (in nanoseconds) to parse the query.
 - **timer_rego_query_compile_ns**: time taken (in nanoseconds) to compile the query.
 - **timer_rego_query_eval_ns**: time taken (in nanoseconds) to evaluate the query.
 - **timer_rego_module_parse_ns**: time taken (in nanoseconds) to parse the input policy module.
 - **timer_rego_module_compile_ns**: time taken (in nanoseconds) to compile the loaded policy modules.
-- **timer_server_handler_ns**: time taken (in nanoseconds) to handle the API request.
+- **timer_server_handler_ns**: time take (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`), 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
 faster to evaluate since OPA will not have to re-parse or compile it. Hence, when the query is served from the cache
@@ -2344,9 +2333,12 @@ Query instrumentation can help diagnose performance problems, however, it can
 add significant overhead to query evaluation. We recommend leaving query
 instrumentation off unless you are debugging a performance problem.
 
-When instrumentation is enabled there are several additional performance metrics
-for the compilation stages. They follow the format of `timer_compile_stage_*_ns`
-and `timer_query_compile_stage_*_ns` for the query and module compilation stages.
+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
+- **timer_compile_stage_*_ns**: Compilation stage timers for the query and module compilation stages
 
 ## Provenance