Enable detailed logging

Enable detailed debug logging for troubleshooting.

This level of logging captures request and response data that contains potentially sensitive information. Do not use this level of logging when working with actual customer data.

Debug Trace logger

The Debug Trace logger records detailed information about the processing of HTTP requests and responses.

To enable the logger, run the following command:

dsconfig set-log-publisher-prop \
  --publisher-name "Debug Trace logger" \
  --set enabled:true

By default, the log file is located at PingAuthorize/logs/debug-trace.

The Debug Trace logger generates various types of log messages, providing insight into different aspects of request processing. The following sections provide two examples of information recorded by the logger.

Service cache logging

The Debug Trace logger can help determine if the policy decision point (PDP) retrieved service data from its cache or from a direct call to the service.

For services without caching enabled, the logger records a message like the following:

[21/Jun/2024:10:58:35.750 +0100] PDP INFO msg=“<service-type> service call: name=example-service, duration=1ms, configuredTimeout=2000ms

For services with caching enabled, the logger records a message like the following:

[21/Jun/2024:10:57:52.142 +0100] PDP INFO msg=“Cache hit for <service-type> service: name=example-service, cacheKey=FD45D66BE078EAF4EE365EA766460CBF”

Learn more about caching in Service caching.

Circuit breaker logging

When circuit breaker functionality is enabled for a service, the Debug Trace logger records a message each time the breaker transitions between states. Circuit breakers can be open (blocking service requests), half-open (allowing test service requests), or closed (allowing service requests).

For example, when a breaker opens, the logger records a message like the following:

[30/May/2025:16:45:31.608 -0500] PDP WARNING correlationID="72a606d1-8576-43e4-8e9d-97045d4885b3" decisionRequestId="499a6253-ea46-435d-9acc-4fb7a149f139" msg="Circuit breaker opened for service: Example service, with ID: ca1fc8ec-69dc-4b90-8676-9a7130e2b72e"

Learn more about circuit breakers in Connecting a service.

Debug logger

The Debug logger records debugging information that a developer might find useful.

The following example enables the log.

dsconfig set-log-publisher-prop \
  --publisher-name "File-Based Debug Logger" \
  --set enabled:true

dsconfig create-debug-target \
  --publisher-name "File-Based Debug Logger" \
  --target-name com.unboundid.directory.broker.http.gateway \
  --set debug-level:verbose

dsconfig create-debug-target \
  --publisher-name "File-Based Debug Logger" \
  --target-name \
  com.unboundid.directory.broker.config.GatewayConfigManager \
  --set debug-level:verbose

dsconfig create-debug-target \
  --publisher-name "File-Based Debug Logger" \
  --target-name \
  com.unboundid.directory.broker.core.policy.PolicyEnforcementPoint \
  --set debug-level:verbose

dsconfig set-log-publisher-prop \
  --publisher-name "File-Based Debug Logger" \
  --set enabled:true

By default, the corresponding log file is located at PingAuthorize/logs/debug.

Policy Decision Logger

Enabled by default, the Policy Decision Logger records decision responses that are received from the policy decision point (PDP).

Regardless of whether PingAuthorize Server is configured to evaluate a policy in embedded or external mode, a policy-decision file logs every policy decision per request. The file is located at PingAuthorize/logs/policy-decision and contains the following information:

Policy-decision response

Each client request triggers a policy-decision response that specifies the inbound actions to perform, and another policy-decision response that specifies the outbound actions to perform. If you think of a policy-decision response as a set or decision tree of policies, all inbound and outbound requests are read from that set or tree.

Policy rules determine whether a request is denied, permitted, or indeterminate.

Most recent policy decision

To debug the most recent inbound request, open the policy-decision log file and locate the highest DECISION requestID in the section near the bottom of the file.

Alternatively, you can use the most recent request timestamp to locate the most recent request.

Policy statements

If the policy contains a statement, it is logged after the policy-decision response JSON. Statements feature the same corresponding requestID as the most recent policy decision.

To increase the level of detail that is returned in PDP decision responses, configure the Policy Decision Service as follows:

dsconfig set-policy-decision-service-prop \
  --add decision-response-view:decision-tree \
  --add decision-response-view:request \
  --add decision-response-view:evaluated-entities \
  --add decision-response-view:evaluation-log-with-attribute-values

Policy Decision views also affect the decision response payload of the request. You can remove added views by using the --remove decision-response-view:<view_name> argument. Learn more in Configuring the Decision Response View.

Configurable attribute logging for embedded mode

When running the Policy Decision Service in embedded mode, you can exercise some control over which attributes get logged as part of the policy-decision response. The dsconfig set-policy-decision-service-prop command supports an attribute-logging argument. This argument allows you to log the full details of the specified attributes when they’re evaluated as part of the policy-decision request.

Configuration for attribute logging will also apply to attributes evaluated as part of policy query requests.

Specifying the attributes query permutation view will override the Policy Decision Service configuration and log all evaluated attributes. Learn more in Configuring the query permutation view.

Here’s an example of how to use the attribute-logging argument for embedded mode:

dsconfig set-policy-decision-service-prop \
  --set embedded-mode-logged-attributes:<attribute1>  \
  --set embedded-mode-logged-attributes:<attribute2>

Attributes specified using this argument are logged only if they get evaluated as part of the of policy-decision request. Enabling certain decision response views could override this configuration and cause all evaluated attributes to be included in the response.

Including additional attributes could cause the Trace Log Publisher or the Policy Decision Log Publisher to record sensitive data.