Lightweight Logging with TextLogger
By: Chris Howlett
Background
Applications need to log. Important reasons for logging are to record errors
and to measure performance. The desktop framework provides developers with
extensive logging facilities and the Microsoft Logging Application Block shines
as a very high-powered (if complex) orchestration of those facilities. However,
there isn't much for the Compact Framework. We don't even have an Event Log.
Now, there is a Debug class with some machinery for directing log messages -
i.e. help in directing where messages go. However, for CF apps I'm satisfied
logging to text files, so this Debug class machinery isn't helpful to me. And we
can't forget the very excellent log4net, which has a CF
implementation. I wanted something a lot lighter than log4net though; something
that doesn't need a manual; something that is very easy to use and very fast. So
I wrote TextLogger. This article describes TextLogger and tells you how to
download it, including source. TextLogger is free.
TextLogger Features
TextLogger is a class that provides simple lightweight logging facilities for
Compact Framework applications. TextLogger's features include
- Easy to use. You can call TextLogger's static Log method without
instantiating any objects. That is, you can log "out of the box" without having
to do any initialization or configuration.
- Log messages are time-stamped to hundredths of a second. This is useful when
you are tracing events for performance analysis. For example, I've found this
very helpful in optimizing algorithms for redrawing custom data grids, where
timings to the nearest second (the best that CF does, out of the box) aren't
good enough.
- Log files are managed automatically. TextLogger writes into a different file
each day and keeps only the most recent seven daily log files. TextLogger writes
these files into the system temporary directory (usually \Temp).
- You can have your apps log to different files if you want. TextLogger
creates log file names from a prefix and the date. An application can change the
prefix that TextLogger uses, by setting its Prefix property.
- You can enable and disable logging at run-time by setting TextLogger's
Enabled property.
- You can make your own trade-off between how low the logging overhead is and
how up-to-date the log file is at any point in time. That is, you can control
when the log file's buffers are flushed. You choose one of three modes
- AutoClose (default). The file is opened and closed for every log message. It
is always up-to-date in the file system, and it can usually be read without
collision by other applications. These other applications might include text
editors, or the ActiveSync explorer, which you might use to copy the log from
your device to the desktop for analysis.
- AutoFlush. The file is opened as needed and is not closed by TextLogger
unless the application requests it. The log file stream is flushed after each
log record is written.
- Manual. The file is opened as needed and is not closed by TextLogger unless
the application requests it. The log file stream is not flushed unless the
Application requests it.
As you would expect, AutoClose is the slowest
and Manual is the fastest. On an iPAQ 2200, with AutoClose the average time to
log a short message with one string parameter to be formatted is around 10.5
milliseconds. The time for AutoFlush is around 4.5 ms. The time for Manual is
around 4.0 ms. For normal logging, AutoClose is easiest and most robust. You
should only consider AutoFlush and Manual if you need very fine performance
measurements with many messages per second.
|
Example
You log a message using formatting, just like the framework WriteLine
functions.
For example
Visual Basic .NET
Class ConsoleApp
Sub Main(ByVal args() As String)
TextLogger.Log("ConsoleApp starting, {0}.", "hello")
End Sub
End Class
Visual C#
class ConsoleApp
{
[STAThread]
static void Main(string[] args)
{
TextLogger.Log("ConsoleApp starting, {0}.", "hello");
}
}
The message logged by the above code might look like this
11:36:01.47 ConsoleApp starting, hello.
|
Downloading TextLogger
Download it here.
The distribution includes the C# class library that contains TextLogger, plus
an example that illustrates logging and also allows you to see and measure
precisely the overheads associated with the three different flush methods.
The example is provided as two projects, one in C# and one in VB.NET. All source is
included.
|