PingFederate Server

Log settings

To help you resolve problems, you can use the Log settings window to temporarily enable detailed, or verbose, message logging for specific server log categories.

About this task

PingFederate records runtime and administrative server activities in <pf_install>/pingfederate/log/server.log. Enabling verbose logging changes the log level from INFO to DEBUG or TRACE, depending on the log category.

Verbose messages in some categories can include sensitive information. Also, logging verbose messages can decrease server performance. Therefore, when you finish troubleshooting, disable verbose logging.

The following table describes the log categories.

Log category Description

Core

Debug logging for core components.

Policy Tree

Debug logging for policy trees.

Data Store Response Times

Log response times for data store requests.

Trusted CAs

Log PingFederate and JRE trusted CAs when they are loaded.

XML Signatures

Debug logging for XML signature operations.

HTTP Request Headers

Log HTTP request headers. PingFederate might log sensitive information, such as passwords, when you enable verbose message logging for this category.

HTTP Request Parameters

Log HTTP GET request parameters. PingFederate might log sensitive information, such as passwords, when you enable verbose message logging for this category.

REST Data Store Requests and Responses

Log REST datastore requests and responses. PingFederate might log sensitive information, such as passwords, when you enable verbose message logging for this category.

You can customize the log categories by editing the configuration file, <pf_install>/pingfederate/server/default/conf/log4j-categories.xml. Changes to this file affect both the Log Settings window and the /serverSettings/logSettings in the administrative API. For more information, see the comments in log4j-categories.xml.

To enable verbose logging:

[discrete]== Steps

  1. Go to System → Server → Log Settings.

  2. Enable Verbose logging for one or more categories.

    By default, no categories have verbose logging enabled.

  3. Click Save.

  4. If PingFederate is deployed in a cluster, replicate the changes to the other servers in the cluster.

    For more information, see Cluster management.

Creating a log category

Create a custom log category to help you report specific troubleshooting information in PingFederate.

About this task

Starting with version 11.2, PingFederate allows you to create custom logging categories. These categories allow you to track activities that are available but aren’t logged by default.

Steps

  1. Open the <pf_install>/pingfederate/server/default/conf/log4j-categories.xml file and add a category entry.

    Example:

    <category id="formAdapter" name="HTML Form Adapter" offLevel="INFO" onLevel="DEBUG" description="Enable debug logging for the PingFederate HTML Form adapter."/>
    Category entry parameters
    Parameter Description

    id

    The reference name for the logger.

    Must be a unique alphanumeric string.

    name

    The friendly name for the logger.

    The name will appear in the admin console, so it should be descriptive of the logger.

    offLevel

    The default level of logging and verbosity for when the category is disabled.

    Valid values are:

    • FATAL

    • ERROR

    • WARN

    • INFO (recommended)

    • DEBUG

    • TRACE

    For more information, see Log4j 2 logging service and configuration.

    onLevel

    The increased level of verbosity for when the category is active. Used to troubleshoot issues.

    Valid values are:

    • FATAL

    • ERROR

    • WARN

    • INFO

    • DEBUG(Recommended)

    • TRACE

    For more information, see Log4j 2 logging service and configuration.

    description

    A friendly description for the logger.

    The description will appear in the admin console.

  2. Save and close the log4j-categories.xml file.

  3. Open the <pf_install>/pingfederate/server/default/conf/log4j2.xml and, under the Loggers section, add a logger entry.

    Example:

    <!-- Form Adapter logging -->
<Logger name="com.pingidentity.adapters.htmlform.idp" level="${sys:pf.log.level.formAdapter:-INFO}"/>

    For the example logger entry sys:pf.log.level.formAdapter:-INFO, the syntax is as follows:

    sys:pf.log.level

    This is a constant value for all logger entries.

    formAdapter

    The id value from the category entry. Case sensitive.

    :-INFO

    The default starting logging level. Should match the offLevel value in the category entry.

  4. Save and close the log4j2.xml file.

  5. Copy both files to each PingFederate instance in the cluster that you want the settings to apply to.

  6. Restart PingFederate.

Removing the Log Settings window

About this task

You can remove the Log Settings window from the administrative console, requiring administrators to use only the administrative API for enabling verbose messaging. The log settings are located in the administrative API at /serverSettings/logSettings.

Steps

  1. Go to the <pf_install>/pingfederate/server/default/data/config-store directory.

  2. Open the org.sourceid.saml20.domain.mgmt.impl.LogSettingsManagerImpl.xml file in a text editor.

  3. Change the value of the ShowLogSettingsPage parameter to false.

  4. Save your changes.