Skip to main content

Replay audit logs against a PDP

Replay the permission checks recorded in your audit logs against a policy decision point (PDP) with the Audit Log Replay API. This page is for operators and developers who want to load test a PDP with real traffic patterns, or check that a policy change keeps past decisions.

When to use Audit Log Replay​

GoalWhat to do
Load test a PDPReplay a busy time range against a test PDP and watch its CPU, memory, and latency.
Reproduce a problemReplay the time range when the problem happened against a PDP you can inspect.
Tune performanceReplay the same time range against PDPs with different configurations and compare their metrics.
Compare decisions before and after a policy changeUse permit test run audit in the Permit CLI. The CLI runs the logged checks against a PDP and lists every decision that differs from the audit log.

The Audit Log Replay API sends the requests and returns right away. The API doesn't compare decisions. To see which decisions changed, use permit test run audit.

Prerequisites​

  • An environment API key for the environment whose audit logs you replay. See Get your API key.
  • A PDP that the Permit cloud can reach over the network, such as a test PDP with a public URL. See Run the PDP.
  • Audit logs in the time range you replay. See View and filter audit logs.
Don't replay against a production PDP

A replay sends every logged check in the time range to the PDP in pdp_url. Against a PDP that serves production traffic, the extra load increases latency for your users.

Start a replay​

Send a POST request to the Audit Log Replay endpoint of the Permit API at https://api.permit.io. Pass your API key in the Authorization: Bearer <YOUR_API_KEY> header.

POST /v2/audit-log-replay

For the full schema, see Run the audit log replay in the API reference.

Request body parameters​

ParameterTypeRequiredDescription
pdp_urlstringYesThe URL of the PDP to replay the checks against, for example http://mydomain.com:7766.
start_timeinteger (UNIX timestamp in seconds)NoThe start of the time range to replay. Defaults to 24 hours ago.
end_timeinteger (UNIX timestamp in seconds)NoThe end of the time range to replay. Defaults to the current time.
concurrency_limitintegerNoThe number of checks the replay sends at the same time. Defaults to 10.
graceful_shutdown_sintegerNoThe graceful shutdown time of the replay, in seconds. Defaults to 60.
The documented maximum for concurrency_limit contradicts its default

The API reference gives concurrency_limit a default of 10 and describes its maximum as 5. A value above 5 can be rejected or capped, so send a value of 5 or lower and read the response instead of relying on the default. To confirm the limit for your account, ask in the Permit Slack community.

Example request​

This request body replays the checks between two timestamps against a test PDP, five at a time:

{
  "pdp_url": "https://example-pdp.permit.io",
  "start_time": 1740832387,
  "end_time": 1743507187,
  "concurrency_limit": 5,
  "graceful_shutdown_s": 60
}

Example response​

The API returns HTTP 202 when the replay starts. document_count is the number of audit log entries the replay sends to the PDP:

{
"message": "Audit log replay started with 2599 documents",
"document_count": 2599
}

Confirm that the replay runs​

  1. Check that the response has a document_count above 0. A count of 0 means the time range has no audit logs for the environment.
  2. Watch the logs or metrics of the PDP in pdp_url. The PDP receives permission checks while the replay runs.

Best practices for a replay​

  1. Start with a short time range and a concurrency_limit of 1 or 2, then raise it toward 5.
  2. Point pdp_url at a test PDP, never at a PDP that serves production traffic.
  3. Replay a time range that represents the traffic you want to test, such as your peak hours.
  4. Watch the PDP's CPU, memory, and response times during the replay to find bottlenecks.

Contents

Edit this page

Need help?