Skip to content

Commit ba31ccd

Browse files
alon-boshizeevmoney
alon-boshi
and
zeevmoney
authored
Enhance Monitoring PDPs documentation (#609)
Co-authored-by: Zeev Manilovich <zeevmoney@users.noreply.github.com> Co-authored-by: Zeev Manilovich <zeevmanilovich@gmail.com>
1 parent 06bc1da commit ba31ccd

3 files changed

Lines changed: 150 additions & 24 deletions

File tree

‎.gitignore‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
# Production
55
/build
6-
6+
/.idea
77
# Generated files
88
.docusaurus
99
.cache-loader
@@ -26,4 +26,5 @@ node_modules/
2626
/playwright-report/
2727
/blob-report/
2828
/playwright/.cache/
29-
screenshots
29+
screenshots
30+
/docs.iml

‎docs/how-to/monitoring-pdps/monitoring-pdps.mdx‎

Lines changed: 142 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,149 @@
1-
# Monitoring Page
1+
---
2+
sidebar_position: 1
3+
title: Monitoring PDPs
4+
---
25

3-
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.
6+
# Monitoring PDPs
47

5-
## **Key Features**
6-
- **Real-time tracking** of PDP activity
7-
- **Advanced filtering** by project, environment, last active time, PDP version, and OPA version
8-
- **Comprehensive insights** for troubleshooting and optimizing policy enforcement
8+
:::note Early Access Program
9+
The PDP Monitoring page is an **Early Access Program (EAP)** feature.
10+
Behavior, UI semantics, data retention, and displayed metadata may change between releases.
11+
:::
912

10-
## **PDP Status Indicators**
11-
- 🟢 **Active** – The PDP instance is currently running
12-
- 🔴 **Inactive** – The PDP instance is not running
13+
## Overview
1314

14-
## **Table Columns**
15-
| Column | Description |
16-
|----------------------|----------------------------------------------|
17-
| **PDP ID** | Unique identifier for each PDP instance |
18-
| **Project** | Associated project name |
19-
| **Environment** | Deployment environment |
20-
| **Last Activation** | Most recent activity timestamp |
21-
| **Data Updated** | Last data update timestamp |
22-
| **PDP Version** | PDP software version |
23-
| **OPA Version** | Open Policy Agent (OPA) version used |
15+
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.
2416

25-
## **API Integration**
26-
The Monitoring Page retrieves data via the [PDP Statistics API](./../../api/pdp-statistics.mdx), ensuring up-to-date insights.
17+
Use the Monitoring page to:
18+
19+
- **Track active PDP instances** across your environments
20+
- **Verify deployment consistency** during rollouts
21+
- **Identify version mismatches** between PDP and OPA
22+
- **Monitor connection status** of your PDP fleet
2723

2824
![Monitoring Page](/images/monitoring/monitoring-page.png)
25+
26+
## Information Displayed per PDP
27+
28+
For each PDP instance, the Monitoring page displays:
29+
30+
| Information | Description |
31+
|------------|-------------|
32+
| **Connection Status** | Current connectivity state (connected / not connected) |
33+
| **PDP Version** | Version of the PDP software running on the instance |
34+
| **OPA Version** | Version of Open Policy Agent bundled with the PDP |
35+
| **Environment** | The environment the PDP is connected to |
36+
| **Project** | Associated project name |
37+
| **Last Activation** | Most recent activity timestamp |
38+
| **Data Updated** | Last data update timestamp |
39+
40+
This information helps operators:
41+
42+
- ✅ Verify **rollout consistency** across deployments
43+
- ✅ Identify **outdated PDP or OPA versions** that need upgrading
44+
- ✅ Correlate behavior with specific **PDP builds** during troubleshooting
45+
46+
## Understanding Connection Status
47+
48+
### Green Status (Connected)
49+
50+
A PDP shown as **green** indicates the instance is currently connected and actively communicating with the Permit control plane.
51+
52+
### Red Status (Not Connected)
53+
54+
:::warning Red Status ≠ Active Failure
55+
A PDP shown as **red** does **not necessarily** indicate an active failure or problem.
56+
:::
57+
58+
A PDP may appear red when:
59+
60+
- The PDP process was **stopped or terminated**
61+
- A container or pod was **restarted during deployment**
62+
- The PDP instance was **decommissioned**
63+
- The PDP has **not checked in recently**
64+
65+
These conditions are **expected**, especially in environments with:
66+
67+
- **Frequent releases** and deployments
68+
- **Autoscaling** that creates and destroys instances
69+
- **Rolling updates** that restart pods
70+
71+
:::info Expected Behavior
72+
Most red PDPs observed in production are **previously running PDPs that were stopped**, not PDPs experiencing live disconnects. This is normal in dynamic environments.
73+
:::
74+
75+
## Common Reasons for Many Red PDPs
76+
77+
If you see many red PDPs in your monitoring view, it's often due to:
78+
79+
- **High deployment frequency** — Frequent releases create new PDP instances while old ones remain visible
80+
- **Rolling updates or pod restarts** — Kubernetes rolling updates restart pods, leaving previous instances visible
81+
- **Short-lived PDP instances** — Autoscaling creates temporary instances that appear red after scaling down
82+
- **Autoscaling events** — Scale-up and scale-down events create and remove PDP instances
83+
84+
:::tip
85+
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.
86+
:::
87+
88+
## Health Checks vs. Sync Operations
89+
90+
It's important to distinguish between two different behaviors when monitoring PDPs:
91+
92+
### Health Check Status (UI)
93+
94+
The connection status shown in the Monitoring UI:
95+
96+
- Reflects whether a PDP is **currently connected** to the control plane
97+
- Does **not** represent historical health check success or failure
98+
- Shows the **real-time state** at the moment you view the page
99+
100+
### Sync / Create Operations (Logs)
101+
102+
When reviewing PDP logs, you may see:
103+
104+
- **Read timeouts** during consistent update requests
105+
- **HTTP 500 errors** during sync operations
106+
107+
:::info
108+
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.
109+
:::
110+
111+
## Timeout Configuration Guidance
112+
113+
PDPs may encounter read timeouts when client-side timeouts are configured too aggressively.
114+
115+
:::tip Recommended Configuration
116+
Use the default `PDP_CONTROL_PLANE_TIMEOUT` (**75 seconds**) to allow the Permit API to manage request duration properly.
117+
118+
Setting timeouts too low (for example, around 5 seconds) can cause unnecessary timeout errors in logs.
119+
:::
120+
121+
## Version Management
122+
123+
The Monitoring page helps you maintain version consistency across your PDP fleet.
124+
125+
### Best Practices
126+
127+
- ✅ Always ensure PDP instances are running a **recent, supported version**
128+
- ✅ Use the Monitoring page to identify **outdated PDP or OPA versions** during and after rollouts
129+
- ✅ Verify version consistency across environments before completing deployments
130+
131+
### Version Information
132+
133+
The Monitoring page displays both:
134+
135+
- **PDP Version** — The version of the Permit PDP software
136+
- **OPA Version** — The version of Open Policy Agent bundled with the PDP
137+
138+
This dual version display helps you:
139+
140+
- Identify when PDP instances need upgrading
141+
- Ensure OPA version consistency across your fleet
142+
- Troubleshoot issues related to specific version combinations
143+
144+
## Related Documentation
145+
146+
- [PDP Statistics API](/api/pdp-statistics) — Programmatic access to PDP monitoring data
147+
- [PDP Webhooks](/api/pdp-webhooks) — Real-time notifications for PDP events
148+
- [PDP Overview](/concepts/pdp/overview) — Learn more about Policy Decision Points
149+
- [PDP Configuration](/concepts/pdp/configuration) — Configure PDP settings and timeouts

‎sidebars.js‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -470,7 +470,11 @@ const sidebars = {
470470
items: [{ type: "autogenerated", dirName: "how-to/use-audit-logs/errors" }],
471471
},
472472
"api/pdp-webhooks",
473-
"how-to/monitoring-pdps/monitoring-pdps",
473+
{
474+
type: "doc",
475+
id: "how-to/monitoring-pdps/monitoring-pdps",
476+
label: "Monitoring PDPs",
477+
},
474478
],
475479
},
476480
{

0 commit comments

Comments
 (0)