NativeSPLogging

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.log messages will also be routed to the web server's own log or the Windows error log.

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 (which is one reason the permission issue noted above has never been seriously addressed). Under routine use, very little ends up in that log (or at least not only there), but one common problem that may depend on using it is the pass-through issue.

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 pick up a change, you will usually need to restart the process involved.

The typical logging levels can be described thusly:

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.

Transaction/Audit

A third log is configured from within the shibd.logger setup file, and typically available in transaction.log.

Pre-V2.5

Each session that's created or removed is logged here along with a variety of general information, including the set of attributes obtained (but not their values). Apart from auditing or tracking down users, the main value of this information is to identify whether the SP received particular attributes or not. If you don't see something here, and there are no ERROR or WARN messages in shibd.log regarding query failures or filtering, then the attribute in question simply wasn't given to the SP.

V2.5 and Above

Since V2.5, 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

Each event type is routed to its own logging category named Shibboleth-TRANSACTION.Type

• 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 Request or Response is used to signify a standardized logout protocol message.

• 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"