PDP Statistics
Permit.io policy decision points (PDPs) report their uptime, version, and platform to Permit, along with which policy and data update messages they received. This page is for operators who monitor PDPs: use the PDP statistics API to list the PDPs connected to an environment, check one PDP, and find update messages that PDPs did not receive.
PDP statistics endpoints
The PDP statistics API has its own base URL: https://pdp-statistics.api.permit.io. In every path, {project} and {environment} accept either the key or the ID of the project and environment.
| Task | Method and path |
|---|---|
| List all PDPs in an environment | GET /v2/stats/{project}/{environment}/pdps |
| Get one PDP | GET /v2/stats/{project}/{environment}/pdps/{pdp_id} |
| List recent update messages and their delivery status | GET /v2/stats/{project}/{environment}/messages |
For every endpoint and field, see the PDP statistics API reference. The OpenAPI spec is at https://pdp-statistics.api.permit.io/v2/openapi.json.
Authenticate to the PDP statistics API
Send an environment API key as a bearer token in the Authorization header. The API key your PDP uses works, as does any other environment API key. See Get your API key.
In the requests below, replace <YOUR API KEY> with the API key, and {project} and {environment} with your project and environment keys or IDs.
List the PDPs in an environment
Send a GET request to the pdps endpoint:
curl --location \
--request GET 'https://pdp-statistics.api.permit.io/v2/stats/{project}/{environment}/pdps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR API KEY>'
The response lists every PDP that has connected to the environment. first_seen_at and last_seen_at show when the PDP first and last reported to Permit, and active shows whether Permit considers the PDP active. pdp_version and opa_version show the PDP and Open Policy Agent (OPA) versions the PDP runs.
{
"data": [
{
"id": "3b66379e-0ff0-42c3-b60c-60e5af45025b",
"org_id": "b1c89115-2675-439e-8a27-187461df3b6e",
"project_id": "10a08cfd-475b-444e-bc8e-03f56acb4a3b",
"env_id": "a3c2b50b-b9c5-41be-b3cb-2b3a84041504",
"first_seen_at": "2024-03-24T22:22:59.131906",
"last_seen_at": "2024-03-24T23:17:27.941948",
"active": true,
"data_updates_accepted": 0,
"pdp_version": "0.2.37",
"opa_version": "0.62.1",
"os_name": "Linux",
"os_machine": "aarch64",
"os_release": "5.10.124-linuxkit",
"os_version": "#1 SMP PREEMPT Thu Jun 30 08:18:26 UTC 2022"
},
{
"id": "3e3611ea-8238-4950-9a81-412bb16ca460",
"org_id": "b1c89115-2675-439e-8a27-187461df3b6e",
"project_id": "10a08cfd-475b-444e-bc8e-03f56acb4a3b",
"env_id": "a3c2b50b-b9c5-41be-b3cb-2b3a84041504",
"first_seen_at": "2024-03-24T22:03:04.572160",
"last_seen_at": "2024-03-24T22:22:56.454870",
"active": false,
"data_updates_accepted": 0,
"pdp_version": "0.2.37",
"opa_version": "0.62.1",
"os_name": "Linux",
"os_machine": "aarch64",
"os_release": "5.10.124-linuxkit",
"os_version": "#1 SMP PREEMPT Thu Jun 30 08:18:26 UTC 2022"
}
]
}
Get statistics for one PDP
To get statistics for one PDP, first find the PDP ID in the PDP container logs. The PDP logs its ID in a line like this:
2024-03-25T05:48:57.717464+0000 | 19691 | horizon.state | INFO | PDP ID is 62b97e3d-a5f2-417f-a6d6-ac010bb7202a
Then send a GET request to the pdps/{pdp_id} endpoint, with {pdp_id} replaced by the PDP ID:
curl --location \
--request GET 'https://pdp-statistics.api.permit.io/v2/stats/{project}/{environment}/pdps/{pdp_id}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR API KEY>'
The response holds the same fields as one entry of the PDP list:
{
"id": "3b66379e-0ff0-42c3-b60c-60e5af45025b",
"org_id": "b1c89115-2675-439e-8a27-187461df3b6e",
"project_id": "10a08cfd-475b-444e-bc8e-03f56acb4a3b",
"env_id": "a3c2b50b-b9c5-41be-b3cb-2b3a84041504",
"first_seen_at": "2024-03-24T22:22:59.131906",
"last_seen_at": "2024-03-24T23:25:30.509943",
"active": true,
"data_updates_accepted": 0,
"pdp_version": "0.2.37",
"opa_version": "0.62.1",
"os_name": "Linux",
"os_machine": "aarch64",
"os_release": "5.10.124-linuxkit",
"os_version": "#1 SMP PREEMPT Thu Jun 30 08:18:26 UTC 2022"
}
Check the delivery status of update messages
Permit sends policy and data updates to PDPs as messages and tracks which PDPs acknowledge each message. To list the recent messages in an environment, send a GET request to the messages endpoint:
curl --location \
--request GET 'https://pdp-statistics.api.permit.io/v2/stats/{project}/{environment}/messages' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR API KEY>'
The response lists the most recent messages first. For each message, pdps.acknowledged_by lists the PDPs that received the message, and pdps.pending lists the PDPs that did not:
{
"data": [
{
"id": "ac52ec15-de8b-4b49-bc20-eebbdc8a79ae",
"topic": "573958d6569b4975b6dccb7c814ed585:data:policy_data/573958d6569b4975b6dccb7c814ed585",
"urls": [],
"sent_count": 2,
"retry_count": 1,
"created_at": "2024-03-25T00:11:16.027910",
"last_sent_at": "2024-03-25T00:11:16.054386",
"next_retry_at": "2024-03-25T00:11:25.984686",
"state": "assumed_ack",
"pdps": {
"acknowledged_by": [
{
"pdp_instance_id": "3b66379e-0ff0-42c3-b60c-60e5af45025b",
"ack_time": "2024-03-25T00:11:17.098168"
}
],
"pending": [
{
"pdp_instance_id": "17b00f8b-9871-43e6-a99a-5285a91548cc",
"last_seen_at": "2024-03-24T20:09:05.856538",
"considered": "dead"
}
]
}
}
]
}
The messages endpoint is paginated with the page and per_page query parameters (up to 100 results per page).
The state field of a message shows its acknowledgement (ack) state. The main values are:
| State | Meaning |
|---|---|
no_ack | No PDP acknowledged the message. This is the state right after Permit sends it. |
partial_ack | Some connected PDPs acknowledged the message and others did not. |
full_ack | All known connected PDPs acknowledged the message. |
assumed_ack | Every PDP that did not acknowledge the message is assumed to be disconnected, because it stopped sending pings. |
assumed_lost | At least one PDP that still sends pings did not acknowledge the message after several retries. The PDP is out of sync. |
For the full list of states, see the messages endpoint reference.
List only lost messages to find sync issues
To find PDPs that are online but out of sync, filter by state=assumed_lost:
curl --location \
--request GET 'https://pdp-statistics.api.permit.io/v2/stats/{project}/{environment}/messages?state=assumed_lost' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR API KEY>'
An empty data list means every online PDP received the recent updates. To get notified of sync errors instead of polling, see PDP sync error webhooks.