Current File(s): conf/logback.xml
Format: Logback
Legacy V2 File(s): conf/logging.xml
Table of Contents |
---|
Overview
...
The Logback manual provides an exhaustive summary of the many options and features that may be configured. We do not attempt here to replicate this information but instead provide information specific to the IdP and instructions for performing simple, common, adjustments. An AdvancedLogging page is also available to capture more advanced examples.
V3.2.0 includes a substantially revised default logging configuration that is not functionally different but is laid out differently and makes use of a logback feature called "variables" that integrates with the property support in the IdP. For the most part, there are just some shortcuts to controlling logging behavior.
General Configuration
The default logging configuration is located in conf/logback.xml and is wrapped with a reloadable service to add flexibility (though you can also cause logback itself to poll for changes if you wish). The reloadability means that you can keep the logging level at WARN until a problem occurs and then change the logging to DEBUG to get more information if the problem persists, without restarting the IdP.
...
Variables and Properties
The default file provided with V3.2.0 is revised to make makes use of a property-like feature of logback called Variable Substitution. Variables are essentially properties and can be declared inline, imported as property files, or declared as system properties. By default, the only properties used that are declared elsewhere are idp.home and a handful of properties for controlling F-TICKS logging, but we do import the conf/idp.properties file for you so that you can choose to declare any custom properties there. Note that other property files are not imported for you unless you do so directly. Also note that unlike most of the IdP configuration using Spring, this property replacement requires the ${property
} syntax.
...
Variable | Default | Function |
---|---|---|
idp.logfiles 3.2 | ${idp.home}/logs | Location of log files |
idp.loghistory 3.2 | 180 | Number of days of logs to keep |
idp.process.appender 3.2 | IDP_PROCESS | Appender to use for diagnostic log (set to ASYNC_PROCESS for high volume DEBUG logging) |
idp.loglevel.idp 3.2 | INFO | Log level for the IdP proper |
idp.loglevel.ldap 3.2 | WARN | Log level for LDAP events |
idp.loglevel.messages 3.2 | INFO | Set to DEBUG for protocol message tracing |
idp.loglevel.encryption 3.2 | INFO | Set to DEBUG to log cleartext versions of encrypted content |
idp.loglevel.opensaml 3.2 | INFO | Log level for OpenSAML library classes |
idp.loglevel.props 3.2 | INFO | Set to DEBUG to log runtime properties during startup |
idp.loglevel.spring 3.2 | ERROR | Log level for Spring Framework (very chatty) |
idp.loglevel.container 3.2 | ERROR | Log level for Tomcat/Jetty (very chatty) |
idp.loglevel.xmlsec 3.2 | INFO | Set to DEBUG for low-level XML Signing/Encryption logging |
...
The idp-warn.log is a filtered view of idp-process.log that includes only messages logged at WARN or higher.
As of V3.2.0, an An additional, optional log is used for capturing F-TICKS records, a special audit format. See the dedicated topic on FTICKSLoggingConfiguration.
Note that some sources of diagnostic messages, Active Directory in particular, will embed non-ASCII data in the messages, which makes the log binary. V3.4.0 ships with an updated LDAP library that The IdP supports a system property (org.ldaptive.response.encodeCntrlChars) you can set to clean that data, with a small cost in extra processing of the data.
Rolling and Compression
The default configuration causes all the log files to be "rolled over" at midnight each night, if the IdP is running, or the next time the IdP starts up afterward. We suggest letting logback handle this and not attempt attempting to use utilities like logrotate for this purpose.
...
Logback has a feature allowing a log appender (like a file) to be wrapped with a buffer that catches the events and writes them out asynchronously. This carries a small risk of event loss (the chance of which can be adjusted) but greatly improves IdP performance at high logging levels. While we do not suggest logging that much in production in most cases, if this becomes necessary for short periods, using this feature is advisable. You can automatically handle diagnostic events asynchronously by setting the idp.process.appender variable to ASYNC_PROCESS (this is commented out by default) and reloading the logging service.Note that the variable declaration and appender are provided with V3.2.0, but this is a logback feature that can be configured by hand with any version of the IdP.
Logging Categories
For the most part, logging is performed on a Java class basis, so a given class will log to a category matching its classname. Logging levels can be adjusted at either the class level, or package level to capture a wider net.
For convenience, a number of variables are now provided (see above) to abstract out the logging categories required for various common needs.
...
Category | Description |
---|---|
Shibboleth-Audit, Shibboleth-Consent-Audit | Categories to which audit messages are written, allowing them to be captured by additional logging destinations |
Shibboleth-FTICKS 3.2 | Category for F-TICKS logging messages. |
PROTOCOL_MESSAGE | A logger for incoming and outgoing XML protocol messages, not active by default |
org.opensaml.saml | Messages related only to receiving, parsing, evaluating security of, producing, and encoding SAML messages (this produces a lot of log messages, especially at IdP startup) |
org.opensaml.saml.saml2.encryption.Encrypter | Logs unencrypted SAML content at DEBUG level, not active by default |
org.opensaml.saml.metadata.resolver | Information regarding metadata loading, refresh, and querying |
net.shibboleth.idp | Messages related to all the IdP's functions, profile handling, authentication, attribute resolution and filtering |
net.shibboleth.idp.authn | Messages related only to authentication |
net.shibboleth.idp.attribute | Messages related to attribute resolution and filtering |
org.ldaptive | Messages related to LDAP library processing (applies to both authentication or attribute lookup) |
...
MDC KEY | Description |
---|---|
idp.jsessionid | The servlet container's JSESSIONID attribute |
idp.remote_addr | The IP address of the remote user-agent. This is the user's browser for front-channel requests and the SP for back-channel requests. |
idp.server_hostname 3.2 | The host name of the server to which the current request was sent |
idp.server_port 3.2 | The port number to which the current request was sent |
...
Code Block | ||||
---|---|---|---|---|
| ||||
<logger name="Shibboleth-Audit" level="ALL" additivity="false"> <appender-ref ref="IDP_AUDIT" /> </logger> <logger name="Shibboleth-Consent-Audit" level="ALL" additivity="false"> <appender-ref ref="IDP_CONSENT_AUDIT"/> </logger> <logger name="Shibboleth-FTICKS" level="ALL" additivity="false"> <appender-ref ref="IDP_FTICKS_SYSLOG"/> </logger> |
V2 Compatibility
Logback was also used in V2, but many of the useful logging categories will have changed due to package naming, library changes, etc., so you will likely need to re-adjust your local configuration, but the format is at least the same.
Note the rename: in V2 the logging configuration was called logging.xml, while the new one is renamed logback.xml to more clearly reflect the format.
...
Notes
The biggest difficulty with noise in these logs relates to the very common occurrence of network connection issues that affect essentially any web server because of factors outside the software's control. These connection issues will typically result in a lot of extraneous ERROR content in both logs that eventually becomes fairly uninteresting to look at.
...