Logging
Diagnostics
The two "halves" of the SP software write to separate diagnostic log files by default, as configured by the shibd.logger and native.logger logging setup files. Some native logging messages will also be routed to the web server's own error log in the case of Apache.
Both "logger" files include several example categories of general interest that may be needed in specific cases in lieu of adjusting the root logging level.
Most of the interesting and relevant information will usually be found in the shibd.log, particularly SAML-related problems, Metadata issues, and most security issues.
It's somewhat rare to actually need the native log so by default it is now routed to syslog or the Windows Event Log depending on platform. (One problem that may depend on it is the issue of content being served without authentication, which may require debugging the behavior of the RequestMap.)
The primary control point for logging is to set the logging level of the "root" logging category, which is the first non-comment line in the logger configuration files. To apply such a change, you will need to restart the process involved.
The typical logging levels can be described thusly:
DEBUG | Low-level tracing, usually unneeded except when isolating crashes or debugging. You should not jump to conclusions about anything you see at this level as it will likely mislead you if you're not one of the developers. Nothing below INFO is really intended for consumption by deployers. |
INFO | Routine indications of activity, usually the default logging level. |
WARN | Indicates something that's potentially a problem for the system, but not a system-level failure that is fatal. Users may or may not be impacted. |
ERROR | Something's wrong. Users are likely to be affected any time one appears. |
CRIT | Something's so wrong that attention is required or widespread problems will result. |
FATAL | Usually indicates a failure to start or continue with operations. |
In most cases, it's unnecessary to raise the logging level to diagnose routine problems. Under normal operation, logging at INFO should be relatively minimal and is suitable for production use. If you see WARN messages, you should review them and at least know if they're significant. If you see ERROR/CRIT/FATAL messages, you should almost certainly be doing something about them.
By default, a dedicated log is also created containing all messages at WARN and higher.
Event Viewer (Windows)
The default native logging on Windows is to the Windows Event Log, which is observable with the Event Viewer. The following configuration snipper (take from the distributed native.logger file) configures the appender:
log4j.appender.native_log=org.apache.log4j.NTEventLogAppender
log4j.appender.native_log.source=Shibboleth Service Provider
log4j.appender.native_log.layout=org.apache.log4j.PatternLayout
log4j.appender.native_log.layout.ConversionPattern=%c %x: %mThe log itself can be found in the Shibboleth folder of the "Applicationd and Services Log"
Transaction/Audit
An additional log is configured from within the shibd.logger setup file, and typically written to transaction.log. The transaction log supports an extensible event model that applies a formatting string to each event (via the tranLogFormat setting in the <OutOfProcess> element). A list of supported event types and fields follows.
Event Types
Type | Description |
|---|---|
Login | Occurs every time a session is created or an error occurs during a login operation. |
Logout | Occurs every time a session is terminated or an error occurs during a logout operation. A subevent of |
AuthnRequest | Occurs every time a request for authentication is issued to an IdP. |
Event Fields
Each event field is represented by a formatting token of "%tok"
Token | Field | Login | Logout | AuthnRequest |
|---|---|---|---|---|
E | exception type | x | x | x |
e | exception message | x | x | x |
S | protocol status code | x | x |
|
SS | protocol sub-status code | x | x |
|
SM | protocol status message | x | x |
|
URL | request URL | x | x | x |
URI | request URI | x | x | x |
s | session ID | x | x | x |
a | client address | x | x | x |
UA | client User-Agent | x | x | x |
app | SP application ID | x | x | x |
SP | SP entityID | x | x | x |
IDP | IdP entityID | x | x | x |
p | identity protocol | x | x | x |
b | identity protocol binding | x | x | x |
n | subject identifier of user | x | x |
|
u | REMOTE_USER | x | x |
|
i | assertion ID | x |
|
|
I | protocol message ID | x | x | x |
II | protocol request ID associated with event | x | x |
|
d | assertion timestamp | x |
|
|
D | protocol message timestamp | x | x | x |
t | authentication timestamp | x |
|
|
x | SAML session index | x | x |
|
ac | SAML authentication context | x |
|
|
attr | list of attributes received | x |
|
|
L | logout result |
| x |
|