|Gibraltar.Agent Namespace : Log Class|
By default the Gibraltar 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 Gibraltar and for receiving log messages from logging systems such as log4net. Messages sent directly to Gibraltar 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 Gibraltar's logging features.
The logging API provides different groups of methods for different levels of simplicity verses flexibility.
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 requring 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.
The Severity Methods (named after each severity level) provide the most commonly-needed features of Gibraltar's logging capability. In order from most to least severe, these are:
Each of these methods in their simplest form takes Category, Caption, and Description instead of just a single Message to take best advantage of Gibraltar'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 correspoding Detail method that supports recording an XML document string with details for more sophisticated examination. This information can be formatted in the Gibraltar 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 Gibraltar.
If you are already using a different logging system than Trace or the Gibraltar 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 exising 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 Gibraltar Agent.
For more information, see Developer's Refrence - 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:
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.
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