This document provides a guide to using the trace functionality in arcplan Engage, and configuring it to meet you requirements.
Some basic attributes of the tracing functionality in arcplan Engage are:
- All trace messages are collected and output by the arcplan Engage server. No log files are created on the client machines.
- Tracing can be configured to filter out messages based on their severity level. There are five defined levels, ordered by severity: DEBUG, INFO, WARN, ERROR, FATAL.
- The engage Server uses the highly configurable log4net utility to send the messages to any combination of output medium, such as files, database tables, system event logs and email recipients.
This document will explain the default trace configuration, and point you in the right direction to configure for more complex requirements.
Trace Configuration file
The arcplan Engage setup installs a default trace configuration, which is explained in the following sections.
If you wish to change your trace configuration, you will need to manually edit the traceconfig.xml file in the folder ProgramData\arcplan\7\Engage\1\arcGallery.Web\.
traceconfig.xml contains a number of <appender>nodes, where an appender defines an output destination for the trace messages. You can add any number of appenders to the configuration.
After editing the traceconfig.xml file the Engage IIS Application needs to be restarted for the changes to take effect.
The Default RollingFile appender
The arcplan Engage setup installs a default traceconfig.xml file with one active appender. This is a RollingFile appender, configured to write trace messages to the file arcGalleryLog.txt.
The appender is configured to format trace messages as in this example:
2011-07-20 14:16:24,220 12 INFO arcVegaSearcher.CVegaSearcher Perform search: IAMSEARCHING
The message comprises of the following parts:
- 2011-07-20 14:16:24,220
- date and time when the message is written to the log file
- the thread on the server which writes the trace messag
- the severity level of the message ( DEBUG, INFO, WARN, ERROR or FATAL)
- the 'logger': this signifies which part of the code produced this message
- Perform search: IAMSEARCHING
- an informative textual message
Each message starts on a new line. New messages are appended to the end of the log file.
The appender is configured to 'roll' when the log file size reaches 100kb. When the log file reaches this limit, a backup is made and the log file emptied. An unlimited number of backup log files are made - they need to be deleted manually.
There are many configuration options for the RollingFile appender - please refer to the log4net documentation for more information.
The (deactivated) Default ADO.NET appender
The installed default traceconfig.xml also contains a disabled ADO.NET appender. This appender is configured to write trace messages into a database table named 'Log' in the engage server's database.
The appender is commented out by default, but exists to help quick configuration if the feature is desired.
Important note regarding message order
Trace messages can originate from the arcplan Engage server or any arcplan Engage client. Messages originating from a client are sent to the server . The server uses log4net to output to the destination(s) defined by the appenders in the traceconfig file.
There is no guarantee that trace messages sent from clients will arrive at the server in the same chronological order in which they were sent.
Trace messages originating from a client have a special format to help determine the correct order when troubleshooting. A client originating message looks like this:
2011-07-20 14:33:44,054 9 INFO arcGallery Client-Time (UTC): 2011-07-20 12:33:44.029 MessageNo: 16, Message: Finished search: IEXPLORER2
The first four parts of the message are the same as server-originating messages; the fifth part of the message comprises of:
- Client-Time (UTC): 2011-07-20 12:33:44.029
- the time when the client sent the message (in coordinated universal time)
- MessageNo: 16,
- a counter specific to the client that sent the message.
- Message: Finished search: IEXPLORER2
- an informative textual message
When troubleshooting difficult problems, we recommend using an ADO.NET appender to write trace messages into a database table where they can then be easily sorted and filtered using SQL select statements.
Configuring the Trace level
The <level> node in the configurations <root> node is used to filter out trace messages based on severity. The default installation sets the root level to WARN - which means that only messages with severity level WARN or higher will be output.
The five valid values for level in order of severity are DEBUG, INFO, WARN, ERROR, FATAL.
Important note: Reducing the trace severity level will result in increased network traffic, as each engage client will be sending more messages to the server for tracing.
Troubleshooting the Trace Configuration
If the tracing is not behaving as you expect, you can turn on the log4net internal debugging. To do this, manually edit the web.config file in the Engage Web Application's folder (typically c:\inetpub\wwwroot\Engage\).
Enter the following settings:
<configuration> ... <system.diagnostics> <trace autoflush="true"> <listeners> <add name="textWriterTraceListener" type="System.Diagnostics.TextWriterTraceListener" initializeData="C:\tmp\log4net.txt" /> </listeners> </trace> </system.diagnostics> <appSettings> <add key="log4net.Internal.Debug" value="true"/> </appSettings> ... </configuration>
With these settings log4net will write internal trace messages to the file "C:\tmp\log4net.txt".
Refer to the log4net internal debugging documentation for more.
For more help on configuring the trace to meet your requirements, please refer to the online log4net documentation: