By default the Loupe Agent will collect trace messages (from System.Diagnostics.Trace) and automatically monitor certain other system events. This Log class provides the API for directly logging to Loupe and for receiving log messages from logging systems such as log4net. Messages sent directly to Loupe will not go through System.Diagnostics.Trace and will not be seen by trace listeners or by other logging systems, but can take direct advantage of Loupe's logging features.

The logging API provides different groups of methods for different levels of simplicity verses flexibility.

• Trace Methods: Designed to mirror the Trace class built into .NET, these provide the simplest API and are a direct substitute for existing calls that use the Trace method (simply change the class name from System.Diagnostics.Trace to Gibraltar.Agent.Log)
• Severity Methods: A method for each Loupe severity from Critical (the most severe) to Verbose (the least). These provide a full featured API for logging directly to Loupe as part of your application.
• Write Methods: Used to forward log messages into the Loupe Agent from an external logging system or logging aggregation class. These expose the most capability but are generally unnecessary outside of the message forwarding scenario.

Trace Methods

The various Trace methods provide a quick way to record a log message at a chosen severity level with the fewest arguments to manage. These methods include direct replacements for Trace.TraceInformation, Trace.TraceWarning, and Trace.TraceError, as well as a Trace() call (replacing the use of Trace.Write and Trace.WriteLine for logging Verbose messages).

In addition to the direct replacement calls for the Trace API an additional TraceCritical Method method was added for logging fatal errors.

Each of these methods also provides an overload which accepts an Exception object as the first parameter. By providing the exception object with the method, extended information about the exception is recorded which can significantly improve the utility of the log information without requiring it to be included in the message.

When using Trace exclusively, it's recommended that you include a call to Trace.Close at the very end of your application's execution. This will ensure that all Trace Listeners are shut down correctly, and the Agent will use this to record that the session closed normally and start its shutdown procedure by automatically calling Log.EndSession.

For more information, see Developer's Reference - Logging - Using with Trace.

Severity Methods

The Severity Methods (named after each severity level) provide the most commonly-needed features of Loupe's logging capability. In order from most to least severe, these are:

• Log.Critical
• Log.Error
• Log.Warning
• Log.Information
• Log.Verbose

Each of these methods in their simplest form takes Category, Caption, and Description instead of just a single Message to take best advantage of Loupe's ability to group similar messages for analysis and reporting. Additional overloads allow an Exception object to be specified (regardless of severity) and allow the message to be committed to disk in the session file before the thread's execution continues.

For more advanced usage, each Severity method has a corresponding Detail method that supports recording an XML document string with details for more sophisticated examination. This information can be formatted in the Loupe Analyst to provide end users with extended drill-in data about a particular situation. Because the logging data is highly compressed (typically 80 percent or more for strings over 5kb), it's safe to record XML documents without overwhelming the session files.

For more information, see Developer's Reference - Logging Directly to Loupe.

Write Method

If you are already using a different logging system than Trace or the Loupe Agent you can forward messages from it into the Agent by using the Write method. The two overloads of the Write method are designed to support both full featured external log systems that can capture extended information, origin information for the log message, and even override the user identity.

Another common scenario supported by Write is an existing application with a central class that all logging is being routed through. The Log.Write method is designed to support this easily while still allowing you to take advantage of the safe formatting and origin determination capabilities of the Loupe Agent.

For more information, see Developer's Reference - Logging - Using with External Log Systems.

Starting a Session

The Log object will attempt to start the first time it is used, or any time a call is made to StartSession. When it starts, it will raise its Log.Initializing event to allow for configuration overrides to be done in code and for the startup sequence to be canceled. If the startup is canceled, all API functions continue to work but no Agent functionality is available. This is a high speed mode that allows any agent overhead to be removed from the process without altering the control flow or recompiling the application.

Ending a Session

It's a best practice at the end of your application's normal execution path to include a call to Log.EndSession. This performs several functions:

1. It marks the session as ending normally. Regardless of how the process exits after EndSession is called, it will not be considered crashed.
2. All queued information is flushed to disk and all subsequent write requests are handled as WaitForCommit requests to ensure that no messages are lost.
3. Various internal changes are made to ensure that the process will exit quickly. If no EndSession call is made, the Agent may keep the process alive even if it normally would have exited.

You can safely call EndSession multiple times.

Configuring the Agent

The agent can be configured in the application configuration file, through code, or both. To configure the agent in code you must subscribe to the Log.Initializing event before the agent is started and then manipulate the Agent configuration object and its child objects. If any configuration was supplied in the application configuration file that will have already been loaded into the configuration objects when the event is raised.

System.Object
   Gibraltar.Agent.Log

Target Platforms: Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

Reference

Log Members
Gibraltar.Agent Namespace

Developer's Reference

Logging - Using with Trace
Logging - Using with External Log Systems
Logging - Using Loupe as a Log System