Tracing Activities and Propagating Context Information

Article
12/21/2010

Retired Content
This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
The latest Enterprise Library information can be found at the Enterprise Library site.

In some cases, you will need to log information at the start and end of a particular activity, including timing information. In addition, you can trace the progress of the activity at selected points in the application. Tracing allows you to associate all events between the start and end of an activity with an ActivityID property and a category. The ActivityID property allows you to correlate log entries that are written during the execution of an activity. You can use filters and categories to direct and control the information produced for an event that can occur in the context of any activity.

Typical Goals

In this scenario, the goal is to log the beginning and end of an activity to a common category. The configuration settings for the category determine the destination of the log entries.

Solution

Configure the application to use the Logging Application Block, specifying the category to be used when tracing activity start and end times. Create an instance of the Tracer class in code where you want the timed event to begin, specifying a configured category. When the Tracer object is created, the activity start time will be logged using the specified category.

using (new Tracer("Log Category"))
{
  // Perform processing to be timed here
}

'Usage
Using New Tracer("Log Category")
  ' Perform processing to be timed here
End Using

Note

The preceding code will result in the Tracer object generating a unique identifier for the activity. You can use this activity identifier to correlate all log entries for particular execution of an activity. Alternatively, you can specify the activity identifier in the code that constructs the Tracer object. The application block uses the .NET Framework CorrelationManager class to maintain the activity identifier.

If you use the Unity Integration approach to create instances of objects from the Logging Application Block, you must use the non-static façade named TraceManager instead of the static Tracer class. For more information about using the Unity Application Block to create and inject instances of Enterprise Library objects, see Creating Objects Using the Unity Application Block.

The end time of the activity is logged using the same category when the Tracer object is disposed. The automatic disposal behavior of the using statement causes the end time to be logged when the scope of the using statement ends.

Propagation of Context Information

The categories associated with a Tracer object remain in effect as long as the Tracer object remains in scope. This means that the categories for a Tracer object are included in the list of categories for any call to the Logger.Write method while that Tracer object is in scope. In the following code, the message written in the call to the Logger.Write method belongs to both the UI Events category and the Debug category.

using (new Tracer("UI Events"))
{
  // The following message will be associated with the "UI Events" and "Debug" categories.
  Logger.Write("My message", "Debug");
}

'Usage
Using New Tracer("UI Events")
  ' The following message will be associated with the  "UI Events" and "Debug" categories.
  Logger.Write("My message", "Debug")
End Using

By using the Logging Application Block, developers can trace the progress of an activity through a series of method calls. You can create log entries that have a common activity identifier by instantiating nested Tracer objects that do not specify an activity identifier. The nested Tracer objects will create log entries with the same activity identifier of the Tracer object currently in scope.

When tracing an activity, you can specify the activity identifier in the outermost Tracer object. If you do not specify an activity identifier, the application block will construct one for you. The application block uses the static property CorrelationManager.ActivityId to maintain the current activity identifier.

LogEntry objects created for nested Tracer objects belong to the category specified for the nested Tracer object as well as to all categories for parent Tracer objects. Categories determine the destinations for the log entries and are used for filtering. For example, in the following code, the nested Tracer object belongs to both category A and category B.

// The LogEntry created for the Tracer to category "A".
using (new Tracer("A"))
{
  // The LogEntry created for this Tracer belongs to both category "A" and category "B".    
  using (new Tracer("B"))
  {
    ...
  }
}

'Usage
' The LogEntry created for the Tracer belongs to category "A".
Using New Tracer("A")
  ' The LogEntry created for this Tracer belongs to both category "A" and category "B".    
  Using New Tracer("B")
    ...
  End Using
End Using

The following code creates log entries that trace the progress of an activity. All log entries for this activity have the same activity identifier. The LogEntry object is associated with the categories UI Events, Data Access Events, and Troubleshooting.

using (new Tracer("UI Events"))
{
  using (new Tracer("Data Access Events"))
  {
    LogEntry logEntry = new LogEntry();
    logEntry.Categories.Add("Troubleshooting");
    Logger.Write(logEntry);
  }
}

'Usage
Using New Tracer("UI Events")
  Using New Tracer("Data Access Events")
    Dim logEntry As New LogEntry()
    logEntry.Categories.Add("Troubleshooting")
    Logger.Write(logEntry)
  End Using
End Using

QuickStart

For an extended example of how to use the Tracer class, see Walkthrough: Tracing Activities and Propagating Context Information.

Usage Notes

Multiple Tracer objects may exist at one time. However, they must be disposed in the reverse order in which they were created. The recommended approach is to create your Tracer objects in the context of a using statement (Using in Visual Basic). This causes your Tracer objects to be disposed in the correct order.

If you explicitly dispose your Tracer objects, dispose them in reverse order than they were created. The following scenario is not supported.

Tracer tracer1 = new Tracer();
Tracer tracer2 = new Tracer();

// INCORRECT: Should dispose tracer2 before tracer1.
tracer1.dispose(); 
tracer2.dispose();

'Usage
Dim tracer1 As Tracer = New Tracer
Dim tracer2 As Tracer = New Tracer

' INCORRECT: Should dispose tracer2 before tracer1.
tracer1.Dispose() 
tracer2.Dispose()