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.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:

DEBUG

Low-level tracing, usually unneeded except when isolating crashes or developing.

INFO

Routine indications of activity, usually the default logging level.

WARN

Indicates something that's noteworthy, but not an actual error.

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 at least know why. If you see ERROR/CRIT/FATAL messages, you should 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"

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