RSS Feed
Download our iPhone app
Browse DevX
Sign up for e-mail newsletters from DevX


Fast and Flexible Logging with Vista's Common Log File System

Microsoft's Common Log File System is an OS-supported logging framework that provides all the logging capabilities you need—and it's available via managed code and your favorite .NET language.

ogging is a vital capability for enterprise-class applications! For example, consider some of the motivations for examining the logs generated by Internet Information Services (IIS):

  • Usability: Which pages are the most popular? Which pages aren't visitors finding?
  • Reliability and supportability: For how long was the site down? How did traffic respond when the site was restored?
  • Performance: How many visitors do we have per day? When is traffic the heaviest?
  • Security and auditing: What is the IP address of an offending visitor? How many times was a particular document downloaded this week?
Until now, adding logging capabilities to your application meant designing, writing, and testing your own logging framework—and there's more to logging than meets the eye. A robust logging framework must handle issues such as:

  • How to manage available disk space
  • How to enforce security
  • Support for multiple log entry formats
  • Granting (or preventing) access to the log from multiple applications simultaneously
During Vista's development, Microsoft focused a great deal of its development efforts on providing core application services in the operating system and exposing those services to the .NET framework. With the new Common Log File System (CLFS), you won't have to reinvent the logging wheel.

The Common Log File System
The Common Log File System (CLFS) is a unified management and storage mechanism for log files. It's native to Windows Vista and later operating systems, but is also available on Windows Server 2003 R2. It has an impressive list of features:

  • Log entry formats are completely customizable.
  • Log files can be stored anywhere.
  • Log files automatically expand or truncate according to policy settings.
  • No need to directly manipulate physical log files.
  • Security controlled by the operating system.
  • Multiple applications can access the same log.
What You Need
To build and run the application you'll need Microsoft Visual Studio 2005, the Microsoft .NET Framework 3.0 redistributables, and Microsoft Vista (or Microsoft Windows Server 2003 R2).

A CLFS log is an abstract concept that represents a collection of log records. A log record is a unit of application data; it's the data your application writes to the log when you encounter an unexpected condition or need to trace an activity.

A CLFS log has two components: the log store and the extents. The log store contains metadata information about the log, and the extents are where CLFS physically stores log records. A small log might have two extents, while a large log might have hundreds of extents. CLFS dynamically grows your application's log by adding extents.

How you chain log records together is entirely up to you.
CLFS stores the log store in a physical file called the log file, which is a small file with a .blf extension. CLFS stores each extent in a physical file called a container. Containers are always multiples of 512 KB, so every container in a CLFS log is the same size. It's no coincidence that containers and log stores are similar to sectors and clusters on a hard disk; Microsoft designed CLFS for high performance.

CLFS stores log records in sequence. There are two kinds of sequences. The first type of sequence is a logical sequence. When you create a log record you can link it to other log records to create logical chains. How you chain log records together is entirely up to you. The second type of sequence is a physical sequence; it's the ordered set of log records in a container file.

Figure 1. The DevX CLFS Sample: This sample application lets you write new log entries and view existing log entries.
Unmanaged windows applications access CLFS through the Win32 API: Clfsw32.h and Clfsw32.dll. Managed .NET applications access CLFS through the .NET 3.0 System.IO.Log namespace. The Win32 CLFS functions emphasize the physical concepts; for example, you add an extent to a log store by passing a log file handle to the AddLogContainer function. In contrast, the .NET CLFS methods emphasize the abstract concepts; for example, you add an extent to a log store by calling the LogStore.Extents.Add method.

Use the Win32 CLFS API if your application isn't managed or if you need fine-tuned control over logs. Otherwise, use the .NET CLFS API—it's a higher level API that's easier to understand and use. Using the .NET CLFS API also allows you to take advantage of .NET's robust serialization support, which is useful for reading and writing log records.

The remainder of this article focuses on the .NET CLFS API. You can download the sample application attached to this article to follow along and experiment as you go. The sample application (see Figure 1) demonstrates the major topics discussed in the article, such as how to create a CLFS log, establish a log policy, and write to and read from the log.

Close Icon
Thanks for your registration, follow us on our social networks to keep up-to-date