--- title: Policy query logging description: Enable and configure policy query logging in PingAuthorize. component: pingauthorize version: 10.2 page_id: pingauthorize:pingauthorize_policy_administration_guide:paz_policy_query_logging canonical_url: https://docs.pingidentity.com/pingauthorize/11.1/pingauthorize_policy_administration_guide/paz_policy_query_logging.html llms_txt: https://docs.pingidentity.com/pingauthorize/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: 2026-01-07T18:03:10Z superseded_by: https://docs.pingidentity.com/pingauthorize/11.1/pingauthorize_policy_administration_guide/paz_policy_query_logging.html section_ids: enable_embedded_debug_logging: Enabling debug logging in embedded PDP mode enabling-policy-query-debug-logging-in-the-administrative-console: Enabling policy query debug logging in the administrative console steps: Steps enabling-policy-query-debug-logging-with-dsconfig: Enabling policy query debug logging with dsconfig steps-2: Steps query_permutation_view_config: Configuring the query permutation view configuring-the-query-permutation-view-in-the-administrative-console: Configuring the query permutation view in the administrative console before-you-begin: Before you begin steps-3: Steps configuring-the-query-permutation-view-with-dsconfig: Configuring the query permutation view with dsconfig before-you-begin-2: Before you begin steps-4: Steps --- # Policy query logging PingAuthorize writes policy query information to the following logs: * `policy-query.log` Records query responses in embedded PDP mode. * `debug-trace.log` Records detailed information about the processing of HTTP requests and responses in embedded PDP mode. To include query requests and responses in `debug-trace.log`: 1. In the administrative console, go to **Logging, Monitoring, and Notifications** and click **Log Publishers**. 2. Click **Debug Trace Logger**. 3. In the **Log Messages to Include** section, on the **Debug Message Type** row, select **policy-query-request-and-response** and click the arrow button. ![Screen capture of the Debug Message Type option for the Debug Trace logger, with the policy-query-request-and-response message type highlighted.](_images/debug-trace-query-request-response.png) * `query-audit.log` Records query decision responses in external PDP mode. ## Enabling debug logging in embedded PDP mode Enable debug logging to provide detailed information when query requests produce errors or unexpected results. In addition to logging the full query request and response, debug logging records details about the resolution and policy dependencies of each attribute included in the query request. This level of detail can be necessary to troubleshoot the individual decision requests that make up a single query request. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Debug logging could log sensitive and personally identifiable information (PII). Enable debug logging only during troubleshooting and disable it afterward. | In debug mode, a policy query audit log entry includes the following fields: * `requestId`: A unique identifier for the query request * `permutationId`: A unique identifier for the query permutation A query permutation is a combination of query attributes used for a decision in the final query response. Use this identifier and the `requestId` for increased visibility of query request information across your logging system. For example, a logged call to an external information point would include identifiers for the request and permutation that invoked that service. * `permutation`: A query permutation as an array of JSON objects containing each query attribute and its value * `response`: The complete, high-verbosity response for a query permutation's associated decision, including expanded errors and other helpful information By default, this field includes details about the resolution and policy dependencies of each attribute involved in the permutation's corresponding decision, along with details about any external service used in that decision. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | You can increase the `response` field's level of detail by controlling the query permutation view. Learn more in [Configuring the query permutation view](#query_permutation_view_config). | The following is an example of a policy query request body and its associated audit log messages. The `response` field is shortened for the sake of brevity. ```json { "query": [ { "attribute": "User" }, { "attribute": "Action", "values": ["view"] }, { "attribute": "Resource", "values": ["account"] } ] } ``` ``` [2024-08-26 16:28:19,173] {"requestId": "20f9adb8-f07a-4dbe-a7e0-6734ab7e12f7", "permutationId": "7cffcc00-eab9-4992-be24-15c554e9fc70","permutation": [{"attribute":"User","value":"{\"id\":1}"},{"attribute":"Action","value":"view"},{"attribute":"Resource","value":"account"}],"response":{"id":"7cffcc00-eab9-4992-be2f-15c554e9fc70","...":"..."}}, {"requestId": "20f9adb8-f07a-4dbe-a7e0-6734ab7e12f7", "permutationId": "3769e5e4-4d35-4385-b15f-299bd0b34d9a", "permutation": [{"attribute":"User", "value":"{\"id\":2}"}, {"attribute":"Action","value":"view"},{"attribute":"Resource","value":"account"}], "response":{"id":"e9118333-eb00-48bc-b25e-2ab9a8deecc3","...":"..."},{"requestId": "20f9adb8-f07a-4dbe-a7e0-6734ab7e12f7", "permutationId": "2784e5e4-4d35-4385-b15f-299bd0b12d9a", "permutation": [{"attribute":"User", "value":"{\"id\":3}"}, {"attribute":"Action","value":"view"},{"attribute":"Resource","value":"account"}], "response":{"id":"e9118333-eb00-48bc-b25e-2ab9a8deecc3","...":"..."}} ``` In this example, each possible combination of the query attributes is represented as a distinct `permutation` with its own identifier and decision response details. These permutations are correlated by a common `requestId`. You can enable debug logging for the policy query audit log in the PingAuthorize admin console or with `dsconfig`. | | | | - | ------------------------------------------------------------------------------------------- | | | By default, the policy query audit log is located at `PingAuthorize/logs/policy-query.log`. | * Admin console * `dsconfig` ## Enabling policy query debug logging in the administrative console ### Steps 1. Go to **Logging, Monitoring, and Notifications** and click **Log Publishers**. 2. Click **Policy Query Logger**. 3. Select the **Include Query Permutations** checkbox. ![Screen capture of the Policy Query Logger configuration page with the Enable Query Permutations check box selected.](_images/enable-query-permutations.png) 4. Click **Save to PingAuthorize Server Cluster**. ## Enabling policy query debug logging with `dsconfig` ### Steps 1. Enable the file-based Policy Query Logger. ```shell dsconfig set-log-publisher-prop --publisher-name "Policy Query Logger" --set enabled:true ``` 2. Use the `dsconfig set-log-publisher-prop` command with the following arguments: ```shell dsconfig set-log-publisher-prop --publisher-name "Policy Query Logger" --set include-query-permutations:true ``` ### Configuring the query permutation view In addition to enabling query permutations in the Policy Query logger, you can specify additional levels of detail to include in each permutation's `response` field. The Policy Query logger provides the following additional views: * `request`: Includes the decision request object * `decision-tree`: Includes details of the policy tree's evaluation flow * `attributes`: Includes details of attributes used during policy evaluation, including the attribute's value and type | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Specifying this view overrides any attribute logging [configured for embedded mode](../../11.1/pingauthorize_server_administration_guide/paz_enable_detailed_logging.html#config_attribute_logging). | * `services`: Includes details of services invoked during policy evaluation | | | | - | ----------------------------------------------------------------------------------------------------------------------------- | | | Specifying additional views will impact performance. Use these views for troubleshooting purposes and disable them afterward. | You can configure the query permutation view in the PingAuthorize admin console or with `dsconfig`. * Admin console * `dsconfig` ## Configuring the query permutation view in the administrative console ### Before you begin Create a Policy Query Logger with [debug logging](#enable_embedded_debug_logging) enabled. ### Steps 1. Go to **Authorization and Policies** and click **Policy Decision Service**. 2. In the **Policy Query Configuration** section, change the **Selected** views included for **Query Logger Permutation View** and click the arrow button. ![Screen capture of the Policy Query Configuration section with the request permutation logger view highlighted.](_images/query-permutation-view-admin-console.png) 3. Click **Save to PingAuthorize Server Cluster**. ## Configuring the query permutation view with `dsconfig` ### Before you begin Create a Policy Query Logger with [debug logging](#enable_embedded_debug_logging) enabled. ### Steps * Use the `dsconfig set-policy-decision-service-prop` command with the `--add query-logger-permutation-view` argument to add query permutation views: ```shell dsconfig set-log-publisher-prop --add query-logger-permutation-view:attributes --add query-logger-permutation-view:services ``` * Use the `dsconfig set-policy-decision-service-prop` command with the `--remove query-logger-permutation-view` argument to remove query permutation views: ```shell dsconfig set-log-publisher-prop --remove query-logger-permutation-view:attributes ``` You can also configure policy query debug logging for policy development and testing in the Policy Editor. Learn more in [Configuring policy query debug logging in the Policy Editor](../../11.1/pingauthorize_server_administration_guide/paz_pe_enable_query_debug_logging.html).