--- title: Logging for Authorize gateway instances description: Configure gateway logging to help manage, troubleshoot, and optimize your gateway instance. component: pingone page_id: pingone:integrations:p1_logging_authz_gateway_instances canonical_url: https://docs.pingidentity.com/pingone/integrations/p1_logging_authz_gateway_instances.html revdate: May 19, 2026 keywords: ["log filtering", "decision logging", "service logging", "troubleshooting"] section_ids: p1_authz_gateway_log_filtering: Log filtering p1_az_gateway_startup_logging: Startup logging p1_authz_gateway_decision_logging: Decision logging p1_authz_gateway_decision_log_config: Decision logging configuration example: Example service-call-logging: Service call logging examples: Examples p1_authz_gateway_connection_logging: PingOne connection logging version-incompatibility: Version incompatibility --- # Logging for Authorize gateway instances Configure logging to help manage, troubleshoot, and optimize your gateway instances. In Authorize gateways, logging provides critical visibility into how your gateway instances operate, enabling you to monitor performance, troubleshoot issues, and optimize policy evaluation. By configuring log filtering, decision logging, and service call logs, you can capture relevant information while protecting sensitive data. ## Log filtering To enhance security, gateway instances filter certain keywords from logs by default. This prevents credentials and other sensitive information from being exposed in log entries. Gateway instances omit log entries that contain the following case-insensitive keywords: * `defaultSharedSecret` * `sharedSecret` * `ASN1` * `password` For debugging, you can disable filtering to include sensitive data in the logs. To override the default behavior, add the `logging.allowSensitiveMaterial` property to your gateway instance [configuration](p1_configure_authz_gateway_instance.html) and set it to `true`: ```json { "logging": [ { "allowSensitiveMaterial": true } ] } ``` ## Startup logging When a gateway instance starts, it logs identifying information for the associated Authorize gateway and PingOne environment. For example (environment and gateway IDs are obscured): ``` 2026-05-10T19:30:05.961Z level=INFO thread=main component=c.p.l.GatewayConfiguration | envId="00********************************" envName="Example Environment" gatewayId="45********************************" gatewayName="Example Gateway" Read gateway credential metadata ``` * `envId`: The unique identifier for the PingOne environment. * `envName`: The name of the PingOne environment. * `gatewayId`: The unique identifier for the Authorize gateway. * `gatewayName`: The name of the Authorize gateway. Use these values to confirm that the gateway instance uses the expected environment and gateway, especially when managing gateway instances across multiple environments. ## Decision logging Decision logging provides detailed insights into how a gateway instance evaluates requests and makes decisions. By default, decision log entries are written to the Docker container's console and include high-level details about attributes, services, and policy elements evaluated in the decision. For example: ``` 2025-01-15T19:20:50.374Z [auditLog] { "id":"2e1cba8f-a4a7-41a8-8a50-301930c3e720", "authorizationVersion":{"id":"b60fbd90-85e3-11ef-9451-b72251ed6dd8"}, "timestamp":"2025-01-15T19:20:49.972105346Z", "elapsedMicroseconds":239714, "decision":"PERMIT", "authorized":true, "statements":[], "status":{"code":"OKAY","messages":[], "errors":[]} "evaluationLog":[{"id":"91d191af-e0ec-422f-a7f7-fce227ed60b7","type":"Attribute","name":"Amount","outcome":{"value":"Resolved","isSuccess":true},"parent":"e2e47b75-8d9d-417b-a652-cc5d604c22da","elapsedTime":8700},{"id":"e2e47b75-8d9d-417b-a652-cc5d604c22da","type":"Rule","name":"Permit payments up to 10000 USD","outcome":{"value":"PERMIT","isSuccess":true},"parent":"622eadcc-e87e-4109-a7e9-9c229bb14e61","elapsedTime":13935},{"id":"28272483-72ec-4f00-bc91-6f90aa0159ad","type":"Rule","name":"Deny payments above 1000 USD","outcome":{"value":"NOT_APPLICABLE","isSuccess":true},"parent":"622eadcc-e87e-4109-a7e9-9c229bb14e61","elapsedTime":1053},{"id":"622eadcc-e87e-4109-a7e9-9c229bb14e61","type":"Policy","name":"Payment checks","outcome":{"value":"PERMIT","isSuccess":true},"parent":"b0c75c6b-3212-4042-b0a0-e3005d557b4f","elapsedTime":16008},{"id":"b0c75c6b-3212-4042-b0a0-e3005d557b4f","type":"PolicySet","name":"Policies","outcome":{"value":"PERMIT","isSuccess":true},"elapsedTime":21815}] } ``` | | | | - | ----------------------------------------------------------------------------------------------------------------------------- | | | To more easily consume logs, you can stream log data from the gateway instance to external destinations like Kafka or Splunk. | When developing and testing authorization policies published to gateway instances, you can configure the granularity of decision log views for enhanced visibility into which policies and rules were evaluated and which attributes or services were invoked in the process. ### Decision logging configuration Using one of the available [configuration methods](p1_configure_authz_gateway_instance.html), pass the `decision-logging` JSON object into your gateway instance and override the default logging configuration. Example `decision-logging` configuration object: ```json { "decision-logging": [ { "name": "auditLog", "details": ["evaluationLog", "services", "request"], "logged-attributes": ["Amount","Payment.consentId"], "log-format": "%date{yyyy-MM-dd'T'HH:mm:ss.SSSXXX,UTC} [%logger] %mdc_properties %msg%n" } ] } ``` Configuration properties for the `decision-logging` object: * `name` (required): A unique name for the logger. Add this name to each log entry by including the `%logger` tag in the `log-format` configuration property. * `details` (required): An array of logging views. Logging views determine the granularity of log entry data. You can include the following logging views in this array: | Logging view | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request` | Includes the full decision request object. | | `statements` | Includes any statements attached to the decision response. | | `errors` | Includes any errors returned in the `status` field of the decision response. | | `attributes` | Includes detailed resolution and value processing information for any attributes evaluated in the decision.By including this view, you can see attribute data after clicking the **Attributes** tab in the **Decision Visualizer**. Learn more in [Visualizing decisions made by Authorize gateway instances](p1_visualize_decisions_by_authz_gateway_instances.html). | | `services` | Includes details for services invoked during policy evaluation.By including this view, you can see service data after clicking the **Services** tab in the Decision Visualizer. Learn more in [Visualizing decisions made by Authorize gateway instances](p1_visualize_decisions_by_authz_gateway_instances.html). | | `evaluationLog` | Includes a list of policy elements evaluated in the decision. | | `decisionTree` | Includes details for the evaluation flow of the policy tree. | | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Selecting the `request`, `attributes`, or `services` logging views might log sensitive and personally identifiable information (PII). Enable these views only during testing and disable them afterward. | * `logged-attributes` (optional): An array of full names of attributes whose data type and value you want to be logged. If included, this property overrides configuration of the `attributes` logging view. | | | | - | ------------------------------------------------------------------------------------------------------------------------------ | | | To obtain an attribute's full name, click the hamburger menu next to the attribute and select **Copy full name to clipboard**. | * `log-format` (optional): A string defining the format for log entries. If no format is specified, the log format defaults to `"%date{yyyy-MM-dd'T'HH:mm:ss.SSSXXX,UTC} [%logger] %mdc_properties %msg%n"`. Learn more about [customizing the log format](https://logback.qos.ch/manual/layouts.html#conversionWord) in the Logback documentation. #### Example The following decision request asks whether the client is authorized to deposit 990 USD into a basic checking account: ``` curl --location 'http://localhost:8080/api/authorize' \ --header 'Authorization: Bearer example-secret' \ --header 'Content-Type: application/json' \ --data ' { "parameters": { "Amount": "990", "Account": "Basic checking", "Payment.consentId": "{{consentID}}" } }' ``` With the above decision request and the `decisionTree` logging view enabled, `debugLog` records the following entry: ``` [2024-08-13 15:29:56,748] { "id": "cda6fd43-e9ae-49de-b822-7479ef2f2b35", "deploymentPackageId": "42b99394-cbb0-46f9-8b9d-bca15cde330e", "timestamp": "2024-08-13T10:48:45.344117Z", "elapsedTime": 649161, "decision": "PERMIT", "authorised": true, "statements": [], "decisionTree": { "id": "9cf53282-0443-44a3-895a-1c413e190177", "nodeType": "PolicySet", "name": "Policies", "targets": [], "elapsedTime": 19914, "combiningAlgorithm": "FirstApplicable{}", "decision": "PERMIT", "attributes": { "Amount": { "id": "1a89a7b2-6034-48fa-ad45-6bb68e454bb5", "name": "Amount", "successful": "true", "elapsedTime": 0, "value": "permit", "type": "NUMBER" } } "applicableChildren": { "Payment checks": { "id": "014fa703-b5a4-4820-8744-2cb0c715fcfd", "nodeType": "Policy", "name": "Payment checks", "sequence": 1, "targets": [], "elapsedTime": 14765, "combiningAlgorithm": "FirstApplicable{}", "decision": "PERMIT", "applicableChildren": { "Permit payments up to 1000 USD": { "id": "1b9fd38e-5713-48f4-9bf1-5ea8d7b98493", "nodeType": "Rule", "name": "Permit payments up to 1000 USD", "sequence": 1, "targets": [], "elapsedTime": 13637, "decision": "PERMIT", "condition": { "less than or equal": { "lhs": { "id": "1a89a7b2-6034-48fa-ad45-6bb68e454bb5", "name": "Amount", "value": 990, "type": "NUMBER" }, "rhs": { "value": 1000, "type": "NUMBER" } }, "result": { "value": "true", "type": "BOOLEAN" } }, "statements": [] } }, "statements": [] } }, "statements": [] } } ``` Using decision log entries, you can visualize the decision flow and other details about recent decisions to make sure the gateway instance evaluates policies according to your expectations. Learn more in [Visualizing decisions made by Authorize gateway instances](p1_visualize_decisions_by_authz_gateway_instances.html). | | | | - | -------------------------------------------------------------------------------------------------- | | | Although you can define multiple decision loggers, this isn't recommended for performance reasons. | ## Service call logging Slow responses from information points can delay policy evaluations or lead to incorrect access decisions. Service call logs help diagnose information point degradation by providing insight into service latency and availability. By default, gateway instances log: * External service calls in the `SERVICE_AUDIT` component * PingOne service calls in the `PINGONE_SERVICE_AUDIT` component The gateway instance logs PingOne service calls when policies use: * Attributes resolved from the [built-in `PingOne.User` attribute](../authorization_using_pingone_authorize/p1_az_built_in_attributes.html#p1_az_built_in_user_attibutes) * **Is Member Of** and **Is Not Member Of** [condition comparators](../authorization_using_pingone_authorize/p1az_conditions.html#p1_az_condition_comparators) The gateway instance records an additional log entry if it uses a [cached](p1_service_caching_authz_gateway_instances.html) service value in an authorization decision. ### Examples > **Collapse: External service call logs** > > The following examples show `SERVICE_AUDIT` log entries generated for various service call results. > > * `HTTP 200; level=INFO` (successful call) > > ``` > 2024-10-03T11:42:13.204Z level=INFO thread=DefaultServiceExecution-Http Service-0 component=SERVICE_AUDIT decisionRequestId=0e70aec0-ba0d-42a5-bfd9-673538b0a8be exchangeId=J9ggyeMm8utrLivF9fj-dw | HTTP service call: name=Payment Service, host=192.168.7.106, duration=14ms, configuredTimeout=2000ms, status=HTTP/1.1 200 OK > ``` > > * `HTTP 4XX, 5XX; level=INFO` (authorization failure) > > ``` > 2024-10-03T11:47:48.280Z level=INFO thread=DefaultServiceExecution-Http Service-0 component=SERVICE_AUDIT decisionRequestId=a2bbdc25-5d15-4cfc-84b0-0ccf9378ce68 exchangeId=Yvg-p4Lyq2CKD2fsSHE7eQ | Error invoking HTTP service: name=Payment Service, host=192.168.7.106, duration=5ms, configuredTimeout=2000ms, error=com.pingidentity.authorize.serviceexecution.ClientServiceExecutionException: Got unsuccessful status code: 401, with body: { > "message": "Unauthorized" > } > ``` > > * `HTTP 429; level=WARN` (rate limit exceeded) > > ``` > 2024-10-03T11:45:50.598Z level=WARN thread=DefaultServiceExecution-Http Service-0 component=SERVICE_AUDIT decisionRequestId=d63629cc-d61f-41e7-8e68-52298a83b533 exchangeId=Wx-T-oESN6uxNRYeu158Tg | Error invoking HTTP service: name=Payment Service, host=192.168.7.106, duration=14ms, configuredTimeout=2000ms, error=com.pingidentity.authorize.serviceexecution.ClientServiceExecutionException: Got unsuccessful status code: 429, with body: { > "message": "Too Many" > } > ``` > > * `level=WARN` (service unresponsive) > > ``` > 2024-10-03T11:50:19.540Z level=WARN thread=DefaultServiceExecution-Payment Service-0 component=SERVICE_AUDIT decisionRequestId=0c907d84-f70d-4c82-893c-a8d0810bae37 exchangeId=jRPBjiXKEFoL06BuOjGieg | Error invoking HTTP service: name=Payment Service, host=192.168.7.106, duration=2004ms, configuredTimeout > ``` > > * Service cache hit > > ``` > 2024-10-04T11:58:19.540Z level=INFO thread=DefaultServiceExecution-RandomUserService-0 component=SERVICE_AUDIT decisionRequestId=b7034567-08da-499g-9b1a-926b8571d565 exchangeId=85sC5rqIn_bPfvnU2u5Mgg | Cache hit for Payment Service: name=PaymentService, cacheKey=3c21d32a-c432-4cf4-99e1-f9e04f32134a_E02083C34EBC29E4A2CD378F4755728, host=localhost > ``` > **Collapse: PingOne service call logs** > > The following examples show `PINGONE_SERVICE_AUDIT` log entries generated by PingOne service calls for group membership checks. > > * `HTTP 200; level=INFO` (successful call) > > ``` > 2025-06-16T14:58:33.651Z level=INFO thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=5ef633c4-1271-4a35-acaf-10faa1ef891b exchangeId=_490Jq7opXV0DARGr4eJmA | HTTP service call: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=358ms, configuredTimeout=1000ms, status=HTTP/2 200 > ``` > > * `HTTP 4XX, 5XX; level=INFO` (authorization failure) > > ``` > 2025-06-16T14:30:28.770Z level=INFO thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=02e41d1b-cd69-4a26-9f7e-bc1434fed11a exchangeId=FWNNUYSYL5toYfmFFXTHEw | Error invoking HTTP service: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=288ms, configuredTimeout=1000ms, error=Got unsuccessful client error code: 403 body: { > "id" : "4614c4fa-b7b1-4977-8134-5dbecffeb494", > "code" : "ACCESS_FAILED", > "message" : "The actor attempting to perform the request is not authorized." > } > ``` > > * `HTTP 429; level=WARN` (rate limit exceeded) > > ``` > 2026-06-16T11:45:50.598Z level=WARN thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=d63629cc-d61f-41e7-8e68-52298a83b533 exchangeId=Wx-T-oESN6uxNRYeu158Tg | HTTP service call: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=358ms, configuredTimeout=1000ms, error=com.pingidentity.authorize.serviceexecution.ClientServiceExecutionException: Got unsuccessful status code: 429, with body: { > "message": "Rate limit exceeded" > } > ``` > > * `level=WARN` (service unresponsive) > > ``` > 2024-10-03T11:50:19.540Z level=WARN thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=0c907d84-f70d-4c82-893c-a8d0810bae37 exchangeId=jRPBjiXKEFoL06BuOjGieg | Error invoking HTTP service: name=IS_MEMBER_OF0, method=GET, host=api.pingone.com, duration=358ms, configuredTimeout=1000ms > ``` > > * PingOne service cache hit > > ``` > 2025-06-17T15:15:43.095Z level=INFO thread=DefaultServiceExecution-IS_MEMBER_OF0-0 component=PINGONE_SERVICE_AUDIT decisionRequestId=21891fbe-1789-4704-a414-25750392d3b0 exchangeId=3zGbrjik4BgSYEFk4g1SsA | Cache hit for PingOne service: name=IS_MEMBER_OF0, cacheKey=B8153ECDBA957D9C36447FDCEC53CEC9, host=api.pingone.com > ``` ## PingOne connection logging Gateway instances maintain a WebSocket Secure connection with the PingOne platform. When this connection fails, the gateway instance logs error messages describing the issue. Connection failures can occur when: * The network is unavailable, blocked by a firewall, or otherwise misconfigured on the client side. * The Authorize gateway associated with the gateway instance has been deleted. * The gateway credential associated with the gateway instance has been deleted. When the gateway instance loses connection, it logs an initial message such as the following: ``` 2025-07-23T17:22:36.340Z level=WARN thread=Ensure connected to all regions daemon thread. component=c.p.l.s.g.WebSocketClientManager | Failed to send 'gatewayConnectionConfiguration' message over the websocket org.eclipse.jetty.websocket.api.exceptions.WebSocketException: Could not connect to websocket server after 146 ms, location=us-east-2 ``` If the connection isn't restored, the gateway instance periodically logs messages such as the following: ``` Caused by: java.util.concurrent.CompletionException: org.eclipse.jetty.websocket.api.exceptions.UpgradeException: org.eclipse.jetty.websocket.core.exception.UpgradeException: Failed to upgrade to websocket: Unexpected HTTP Response Status Code: 403 Forbidden ``` To restore connectivity: * Verify that your network configuration allows outbound WebSocket connections to the relevant PingOne geography endpoint. Learn more in [Gateway access](p1_authz_gateway_requirements.html#p1_authz_gateway_access). * Verify that the associated Authorize gateway still exists and that the gateway credential hasn't been deleted. If the gateway has been deleted, [create a new Authorize gateway](p1_add_authz_gateway.html), [generate a new gateway credential](p1_create_delete_gateway_credential_authz.html), and [restart the gateway instance](p1_start_authz_gateway_instance.html) with the new credential. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you restart a gateway instance, it uses the authorization policy version configured for the associated Authorize gateway. If this version differs from the one currently published to the gateway instance, the published version is replaced. | * If the gateway instance can't establish a connection to PingOne at startup, you must restart the gateway instance after resolving the underlying issue. The gateway instance can automatically restore its connection without manual intervention after temporary network interruptions. ### Version incompatibility When you start a gateway instance that doesn't support features in the authorization policy version published to the gateway, the system logs an error message such as the following: ``` Failed to deploy configuration from PingOne: authorization version 3189260-68a9-11f0-a6b8-85c37b3173e9 includes policy features unsupported by application version 1.0. Upgrade the application to the latest version to ensure compatibility. ``` To resolve this issue and ensure version compatibility, [upgrade](p1_upgrade_authz_gateway_instance.html) your gateway instance to the latest version. You can find information about version-specific feature support in [Authorize gateway version history](p1_authz_gateway_version_history.html).