2.3. lars.iis - Reading IIS Logs

This module provides a wrapper for W3C extended log files, typically used by the Microsoft IIS web-server.

The IISSource class is the major element that this module provides; this is the class which wraps a file-like object containing a W3C formatted log file and yields rows from it as tuples.

2.3.1. Classes

class lars.iis.IISSource(source)[source]

Wraps a stream containing a IIS formatted log file.

This wrapper converts a stream containing a IIS formatted log file into an iterable which yields tuples. Each tuple is a namedtuple instance with the fieldnames of the tuple being the sanitized versions of the field names in the original log file (as specified in the #Fields directive).

The directives contained in the file can be obtained from attributes of the wrapper itself (useful in the case that relative timestamps, e.g. with the #Date directive, are being used) in which case the attribute will be the lower-cased version of the directive name without the # prefix.

Parameters:source – A file-like object containing the source stream
count

Returns the number of rows successfully read from the source

date

The timestamp specified by the last encountered #Date directive (if any), as a DateTime instance

fields

A sequence of fields names found in the #Fields directive in the file header

finish

The timestamp found in the #End-Date directive (if any, as a DateTime instance)

remark

The remarks recorded in the #Remark directive (if any)

software

The name of the software which produced the source file as given by the #Software directive (if any)

start

The timestamp found in the #Start-Date directive (if any), as a DateTime instance

version

The version of the source file, as given by the #Version directive in the header

2.3.2. Exceptions

class lars.iis.IISError(message, line_number=None, line=None)[source]

Base class for IISSource errors.

Exceptions of this class take the optional arguments line_number and line for specifying the index and content of the line that caused the error respectively. If specified, the __str__() method is overridden to include the line number in the error message.

Parameters:
  • message (str) – The error message
  • line_number (int) – The 1-based index of the line that caused the error
  • line (str) – The content of the line that caused the error
exception lars.iis.IISDirectiveError(message, line_number=None, line=None)[source]

Raised when an error is encountered in any #Directive.

exception lars.iis.IISFieldsError(message, line_number=None, line=None)[source]

Raised when an error is encountered in a #Fields directive.

exception lars.iis.IISVersionError(message, line_number=None, line=None)[source]

Raised for a #Version directive with an unknown version is found.

exception lars.iis.IISWarning[source]

Raised when an error is encountered in parsing a log row.

2.3.3. Examples

A typical usage of this class is as follows:

import io
from lars import iis, csv

with io.open('logs\iis.txt', 'rb') as infile:
    with io.open('iis.csv', 'wb') as outfile:
        with iis.IISSource(infile) as source:
            with csv.CSVTarget(outfile) as target:
                for row in source:
                    target.write(row)

2.3.4. Note for maintainers

The draft standard for the W3C Extended Log File Format is not well written (see the various notes and comments in the code); actual practice deviates from the draft in several areas, and the draft is deficient in describing what is potentially permitted in other areas.

Examples of the format as produced by IIS (the major user of the draft) can be found on MSDN. When maintaining the code below, please refer to both the draft (for information on what could be included in W3C log files) as well as the examples (for information on what typically is included in W3C log files, even when it outright violates the draft), and bear in mind Postel’s Law.