From 330ccb58a7800b5ea95cb590603881f72c6317a3 Mon Sep 17 00:00:00 2001 From: alon-boshi Date: Mon, 26 Jan 2026 10:50:14 +0200 Subject: [PATCH 1/7] Enhance Monitoring PDPs documentation --- .../monitoring-pdps/monitoring-pdps.mdx | 169 +++++++++++++++--- sidebars.js | 6 +- 2 files changed, 146 insertions(+), 29 deletions(-) diff --git a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx index 611c4e6b9..d7a5433dc 100644 --- a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx +++ b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx @@ -1,28 +1,141 @@ -# Monitoring Page - -The **Monitoring Page** provides real-time visibility into active and past **PDP instances** in your environment. It offers a centralized view of your **PDPs**, displaying their activity status, update frequency, and metadata. - -## **Key Features** -- **Real-time tracking** of PDP activity -- **Advanced filtering** by project, environment, last active time, PDP version, and OPA version -- **Comprehensive insights** for troubleshooting and optimizing policy enforcement - -## **PDP Status Indicators** -- 🟢 **Active** – The PDP instance is currently running -- 🔴 **Inactive** – The PDP instance is not running - -## **Table Columns** -| Column | Description | -|----------------------|----------------------------------------------| -| **PDP ID** | Unique identifier for each PDP instance | -| **Project** | Associated project name | -| **Environment** | Deployment environment | -| **Last Activation** | Most recent activity timestamp | -| **Data Updated** | Last data update timestamp | -| **PDP Version** | PDP software version | -| **OPA Version** | Open Policy Agent (OPA) version used | - -## **API Integration** -The Monitoring Page retrieves data via the [PDP Statistics API](./../../api/pdp-statistics.mdx), ensuring up-to-date insights. - -![Monitoring Page](/images/monitoring/monitoring-page.png) +# Monitoring PDPs +:::note Early Access Program +The PDP Monitoring page is an **Early Access Program (EAP)** feature. +Behavior, UI semantics, data retention, and displayed metadata may change between releases. +::: + +## Overview + +The **PDP Monitoring** page provides real-time visibility into **PDP instances** registered with the Permit control plane. It is designed for **operational awareness**, not as a historical audit or incident timeline. + +Use the Monitoring page to: + +- **Track active PDP instances** across your environments +- **Verify deployment consistency** during rollouts +- **Identify version mismatches** between PDP and OPA +- **Monitor connection status** of your PDP fleet + +## Information Displayed per PDP + +For each PDP instance, the Monitoring page displays: + +| Information | Description | +|------------|-------------| +| **Connection Status** | Current connectivity state (connected / not connected) | +| **PDP Version** | Version of the PDP software running on the instance | +| **OPA Version** | Version of Open Policy Agent bundled with the PDP | +| **Environment** | The environment the PDP is connected to | +| **Project** | Associated project name | +| **Last Activation** | Most recent activity timestamp | +| **Data Updated** | Last data update timestamp | + +This information helps operators: + +- ✅ Verify **rollout consistency** across deployments +- ✅ Identify **outdated PDP or OPA versions** that need upgrading +- ✅ Correlate behavior with specific **PDP builds** during troubleshooting + +## Understanding Connection Status + +### Green Status (Connected) + +A PDP shown as **green** indicates the instance is currently connected and actively communicating with the Permit control plane. + +### Red Status (Not Connected) + +:::warning Red Status ≠ Active Failure +A PDP shown as **red** does **not necessarily** indicate an active failure or problem. +::: + +A PDP may appear red when: + +- The PDP process was **stopped or terminated** +- A container or pod was **restarted during deployment** +- The PDP instance was **decommissioned** +- The PDP has **not checked in recently** + +These conditions are **expected**, especially in environments with: + +- **Frequent releases** and deployments +- **Autoscaling** that creates and destroys instances +- **Rolling updates** that restart pods + +:::info Expected Behavior +Most red PDPs observed in production are **previously running PDPs that were stopped**, not PDPs experiencing live disconnects. This is normal in dynamic environments. +::: + +## Common Reasons for Many Red PDPs + +If you see many red PDPs in your monitoring view, it's often due to: + +- **High deployment frequency** — Frequent releases create new PDP instances while old ones remain visible +- **Rolling updates or pod restarts** — Kubernetes rolling updates restart pods, leaving previous instances visible +- **Short-lived PDP instances** — Autoscaling creates temporary instances that appear red after scaling down +- **Autoscaling events** — Scale-up and scale-down events create and remove PDP instances + +:::tip +Stopped PDPs may remain visible in the monitoring view, which can lead to an accumulation of red PDPs over time. This is expected behavior and does not indicate a problem with your active PDPs. +::: + +## Health Checks vs. Sync Operations + +It's important to distinguish between two different behaviors when monitoring PDPs: + +### Health Check Status (UI) + +The connection status shown in the Monitoring UI: + +- Reflects whether a PDP is **currently connected** to the control plane +- Does **not** represent historical health check success or failure +- Shows the **real-time state** at the moment you view the page + +### Sync / Create Operations (Logs) + +When reviewing PDP logs, you may see: + +- **Read timeouts** during consistent update requests +- **HTTP 500 errors** during sync operations + +:::info +These log entries do **not** indicate PDP disconnects or health check failures. They are typically related to **client-side timeout configuration** and are separate from the connection status shown in the UI. +::: + +## Timeout Configuration Guidance + +PDPs may encounter read timeouts when client-side timeouts are configured too aggressively. + +:::tip Recommended Configuration +Use the default `PDP_CONTROL_PLANE_TIMEOUT` (**75 seconds**) to allow the Permit API to manage request duration properly. + +Setting timeouts too low (for example, around 5 seconds) can cause unnecessary timeout errors in logs. +::: + +## Version Management + +The Monitoring page helps you maintain version consistency across your PDP fleet. + +### Best Practices + +- ✅ Always ensure PDP instances are running a **recent, supported version** +- ✅ Use the Monitoring page to identify **outdated PDP or OPA versions** during and after rollouts +- ✅ Verify version consistency across environments before completing deployments + +### Version Information + +The Monitoring page displays both: + +- **PDP Version** — The version of the Permit PDP software +- **OPA Version** — The version of Open Policy Agent bundled with the PDP + +This dual version display helps you: + +- Identify when PDP instances need upgrading +- Ensure OPA version consistency across your fleet +- Troubleshoot issues related to specific version combinations + +## Related Documentation + +- [PDP Statistics API](/api/pdp-statistics) — Programmatic access to PDP monitoring data +- [PDP Webhooks](/api/pdp-webhooks) — Real-time notifications for PDP events +- [PDP Overview](/concepts/pdp/overview) — Learn more about Policy Decision Points +- [PDP Configuration](/concepts/pdp/configuration) — Configure PDP settings and timeouts diff --git a/sidebars.js b/sidebars.js index a4af947d9..82a10dbf9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -470,7 +470,11 @@ const sidebars = { items: [{ type: "autogenerated", dirName: "how-to/use-audit-logs/errors" }], }, "api/pdp-webhooks", - "how-to/monitoring-pdps/monitoring-pdps", + { + type: "doc", + id: "how-to/monitoring-pdps/monitoring-pdps", + label: "Monitoring PDPs", + }, ], }, { From 2e87cf57788f12bf6472aa64585e2b8bcecf44f3 Mon Sep 17 00:00:00 2001 From: alon-boshi Date: Mon, 26 Jan 2026 10:53:54 +0200 Subject: [PATCH 2/7] cr fix --- docs/how-to/monitoring-pdps/monitoring-pdps.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx index d7a5433dc..53499f81a 100644 --- a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx +++ b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx @@ -135,7 +135,7 @@ This dual version display helps you: ## Related Documentation -- [PDP Statistics API](/api/pdp-statistics) — Programmatic access to PDP monitoring data -- [PDP Webhooks](/api/pdp-webhooks) — Real-time notifications for PDP events -- [PDP Overview](/concepts/pdp/overview) — Learn more about Policy Decision Points -- [PDP Configuration](/concepts/pdp/configuration) — Configure PDP settings and timeouts +- [PDP Statistics API](../../api/pdp-statistics) — Programmatic access to PDP monitoring data +- [PDP Webhooks](../../api/pdp-webhooks) — Real-time notifications for PDP events +- [PDP Overview](../../concepts/pdp/overview) — Learn more about Policy Decision Points +- [PDP Configuration](../../concepts/pdp/configuration) — Configure PDP settings and timeouts From 7fcba93267de0892ffccb1e996053bf8bf0d810e Mon Sep 17 00:00:00 2001 From: alon-boshi Date: Sun, 1 Feb 2026 15:18:47 +0200 Subject: [PATCH 3/7] fixed cr --- docs/how-to/monitoring-pdps/monitoring-pdps.mdx | 14 ++++++++++---- sidebars.js | 2 +- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx index 53499f81a..500a8f552 100644 --- a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx +++ b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx @@ -1,4 +1,10 @@ +--- +sidebar_position: 1 +title: Monitoring PDPs +--- + # Monitoring PDPs + :::note Early Access Program The PDP Monitoring page is an **Early Access Program (EAP)** feature. Behavior, UI semantics, data retention, and displayed metadata may change between releases. @@ -135,7 +141,7 @@ This dual version display helps you: ## Related Documentation -- [PDP Statistics API](../../api/pdp-statistics) — Programmatic access to PDP monitoring data -- [PDP Webhooks](../../api/pdp-webhooks) — Real-time notifications for PDP events -- [PDP Overview](../../concepts/pdp/overview) — Learn more about Policy Decision Points -- [PDP Configuration](../../concepts/pdp/configuration) — Configure PDP settings and timeouts +- [PDP Statistics API](/api/pdp-statistics) — Programmatic access to PDP monitoring data +- [PDP Webhooks](/api/pdp-webhooks) — Real-time notifications for PDP events +- [PDP Overview](/concepts/pdp/overview) — Learn more about Policy Decision Points +- [PDP Configuration](/concepts/pdp/configuration) — Configure PDP settings and timeouts diff --git a/sidebars.js b/sidebars.js index 82a10dbf9..a17d1b6f7 100644 --- a/sidebars.js +++ b/sidebars.js @@ -472,7 +472,7 @@ const sidebars = { "api/pdp-webhooks", { type: "doc", - id: "how-to/monitoring-pdps/monitoring-pdps", + id: "how-to/monitoring-pdps", label: "Monitoring PDPs", }, ], From 6b0b6362277bb87e6eaa6fa2d2c690cc3901aa45 Mon Sep 17 00:00:00 2001 From: alon-boshi Date: Sun, 1 Feb 2026 15:22:13 +0200 Subject: [PATCH 4/7] cr --- sidebars.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars.js b/sidebars.js index a17d1b6f7..82a10dbf9 100644 --- a/sidebars.js +++ b/sidebars.js @@ -472,7 +472,7 @@ const sidebars = { "api/pdp-webhooks", { type: "doc", - id: "how-to/monitoring-pdps", + id: "how-to/monitoring-pdps/monitoring-pdps", label: "Monitoring PDPs", }, ], From dbde628876df0e4a0c996be69fe3d443a6e30973 Mon Sep 17 00:00:00 2001 From: Zeev Manilovich Date: Sun, 1 Feb 2026 15:36:11 +0200 Subject: [PATCH 5/7] ignore --- .gitignore | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 89140cf85..15fadde11 100644 --- a/.gitignore +++ b/.gitignore @@ -26,4 +26,5 @@ node_modules/ /playwright-report/ /blob-report/ /playwright/.cache/ -screenshots \ No newline at end of file +screenshots +/docs.iml From 38a379b4e6c2a4b02c3c3c02645666208359f1e8 Mon Sep 17 00:00:00 2001 From: Zeev Manilovich Date: Sun, 1 Feb 2026 15:37:24 +0200 Subject: [PATCH 6/7] wip --- .gitignore | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 15fadde11..c79fbf94f 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,7 @@ # Production /build - +/.idea # Generated files .docusaurus .cache-loader From f63dcc6a898880937069d9022c003b82803618f0 Mon Sep 17 00:00:00 2001 From: alon-boshi Date: Sun, 1 Feb 2026 16:07:33 +0200 Subject: [PATCH 7/7] added removed screenshot --- docs/how-to/monitoring-pdps/monitoring-pdps.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx index 500a8f552..bf2a38909 100644 --- a/docs/how-to/monitoring-pdps/monitoring-pdps.mdx +++ b/docs/how-to/monitoring-pdps/monitoring-pdps.mdx @@ -21,6 +21,8 @@ Use the Monitoring page to: - **Identify version mismatches** between PDP and OPA - **Monitor connection status** of your PDP fleet +![Monitoring Page](/images/monitoring/monitoring-page.png) + ## Information Displayed per PDP For each PDP instance, the Monitoring page displays: