From 3c5b7c6c9a7645d32c2a3976849784cfd7c475ef Mon Sep 17 00:00:00 2001 From: Anivar Aravind Date: Wed, 25 Feb 2026 18:30:01 +0530 Subject: [PATCH] docs: Document metrics for http.send, regex, and glob builtins (#8103) Fixes #6730 Signed-off-by: Anivar A Aravind --- docs/docs/policy-reference/builtins/glob.mdx | 8 ++++++++ docs/docs/policy-reference/builtins/http.mdx | 10 ++++++++++ docs/docs/policy-reference/builtins/regex.mdx | 8 ++++++++ 3 files changed, 26 insertions(+) diff --git a/docs/docs/policy-reference/builtins/glob.mdx b/docs/docs/policy-reference/builtins/glob.mdx index f8294053d6..b038e38d62 100644 --- a/docs/docs/policy-reference/builtins/glob.mdx +++ b/docs/docs/policy-reference/builtins/glob.mdx @@ -77,3 +77,11 @@ 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 `?metrics=true` is specified in API requests, `glob.match` operations expose the following per-query metrics: + +| Metric | Description | +| ------ | ----------- | +| `counter_rego_builtin_glob_interquery_value_cache_hits` | Number of compiled glob patterns served from the inter-query value cache. Only present when [inter-query value caching](/docs/configuration/#caching) is enabled and a previously compiled pattern is reused | diff --git a/docs/docs/policy-reference/builtins/http.mdx b/docs/docs/policy-reference/builtins/http.mdx index b09cf3f2b9..820d56b8dd 100644 --- a/docs/docs/policy-reference/builtins/http.mdx +++ b/docs/docs/policy-reference/builtins/http.mdx @@ -113,3 +113,13 @@ 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 `?metrics=true` is specified in API requests, `http.send` operations expose the following per-query metrics: + +| 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. Only appears when [inter-query caching is enabled](/docs/configuration/#caching) in OPA's configuration and the `http.send` request configuration has `cache` or `force_cache` set to `true` | +| `counter_rego_builtin_http_send_network_requests` | Number of actual network requests made, excluding cached responses | diff --git a/docs/docs/policy-reference/builtins/regex.mdx b/docs/docs/policy-reference/builtins/regex.mdx index eb3f99e2d2..66cf3a22a2 100644 --- a/docs/docs/policy-reference/builtins/regex.mdx +++ b/docs/docs/policy-reference/builtins/regex.mdx @@ -110,3 +110,11 @@ 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. + +## Performance Metrics + +When `?metrics=true` is specified in API requests, regex operations expose the following per-query metrics: + +| Metric | Description | +| ------ | ----------- | +| `counter_rego_builtin_regex_interquery_value_cache_hits` | Number of compiled regex patterns served from the inter-query value cache. Only present when [inter-query value caching](/docs/configuration/#caching) is enabled and a previously compiled pattern is reused |