Page tree
Skip to end of metadata
Go to start of metadata

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.

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.

Windows Event Viewer

The default native logging 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: %m

The 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
TypeDescription
LoginOccurs every time a session is created or an error occurs during a login operation.
LogoutOccurs 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.
AuthnRequestOccurs 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




  • No labels