Web Agent Logging in 6.x

Document ID : KB000025187
Last Modified Date : 14/02/2018
Show Technical Document Details

Description:

In 6.x there are two Web Agent logs instead of one. The 5.x parameters are ignored, how can the 6.x logs be adjusted and controlled?

Solution:

In 6.x of the SiteMinder Web Agent there are two logs, an error and a trace log.
They are both controlled in the Agent Configuration Object. This is controlled in the Administration GUI unless the parameter "AllowLocalConfig" is set to yes. Then it is controlled by either the Administration GUI or the Local configuration file. If this is the case, then one must be aware of the fact any Web Agent parameter defined in both places will take the default. In the case of logging, this will turn off logging because the default for logfilename is nothing.

Please note, as of this writing, the only valid rolling is LogFileSize and TraceFileSize respectively. If you choose to use other methods, please turn off the agent while moving the log file.

The following are the valid error log parameters (explanations below are shown with defaults):
LogAppend, LogFile, LogFileName, LogFileSize, LogFilesToKeep, LogLocalTime

LogAppend='no' This determines if we use a new log each time logging starts or if we should append the old one. Support recommends to keep the default.
LogFile='no' This determines if there is a log file as long as LogFileName is populated. Support recommends to use error logging and adjusting this to yes.
LogFileName='' This is the location of the log file. It must be set to enable logging. The web agent must be able to write to this location.
LogFileSize='100' This is the maximum size in MB of the file. This will cause a log to roll and append a number to the log file when rolling. Support recommends a value of 100.
LogFilesToKeep='' This was introduced in 6.0 QMR5 HF25 and sets a maximum amount of files to keep. If 0 or unset it will default to manual clean up.
LogLocalTime='yes' Unless you have multiple agents across multiple time zones this is probably best kept in local time. If you have to compare agents around the world then logging them all in GMT may be easier to synchronize the time. That is accomplished by setting this to no.

The Following are valid trace log parameters (explanations below are shown with defaults):
TraceAppend, TraceConfigFile, TraceDelimiter, TraceFile, TraceFileName, TraceFileSize, TraceFilesToKeep

TraceAppend='no' This determines if we use a new log each time logging starts or if we should append the old one. Support recommends to keep the default.
TraceConfigFile='' This is also not dynamic to set it and will require a restart to pick up. Support suggests setting this and manipulating the file it is set to, as the file is read upon enabling of tracing
TraceDelimiter='' When set to nothing will use [] as delimiters which is required by support. Support Strongly encourages leaving this blank
TraceFile='no' Support recommends using this to turn tracing on as needed and filling out all the other parameters you wish to use.
TraceFileName='' This has no default and must be set to enable trace logging. Like LogFileName this must be a writable location
TraceFileSize='100' Is the maximum the trace file will grow to before being rolled and is in MB. Support recommends that this be set to 100
TraceFilesToKeep='' was introduced in 6.0 QMR5 HF25 and sets a maximum amount of files to keep. If 0 or unset it will default to manual clean up.

As for configuring the Web Agent Trace file, the following example is a good starting point. Please note the following example includes both the Traditional and Framework Agent components in one line. This allows one setting useful for both Traditional and Framework Agents. In the default WebagentTrace.conf these sections are separate. You may adjust for your situation. Please note filters may also be used but they are advanced and covered by the documentation so they are not covered here.
The configuration consists of two lines, one for Components and one for Data.

Components: AgentFramework, HTTPAgent, WebAgent
Data: Date, PreciseTime, Pid, Tid, TransactionID, User, Domain, Realm, Action, Resource, Message

At a minimum you should have the following Data:

  • Date in order to synchronize with other logs on the server

  • ( Precise ) Time in order to synchronize with other logs on the server

  • Pid (Process ID) in order to synchronize between Error and Trace logs, and to parse out transactions

  • Tid (Thread ID) in order to synchronize between Error and Trace logs, and to parse out transactions

  • TransactionID in order to synchronize between Agents as well as to the Policy Server(s)

  • User to know which user this is in response to

  • Domain to know which domain is being used

  • Realm to know which realm is being used

  • Action to know what action is taken

  • Resource to know the resource being accessed

  • Message to know what is happening with this entry