Custom Date/Time Formats

This article authored by "Friedrich Software Resources", an Urchin Software Authorized Consultant.

Custom Date/Time Formats

Introduction

Urchin can process virtually any date or time format contained in a log file. The only requirement is to provide Urchin with the necessary date or time format which matches the pattern of the date contained in the log file. This article describes the variables used to specify the date or time format. These formats are specified inside a custom log format file. Please see the "Custom Log Formats" article above in this section.

How Date/Time Parsing Works

Urchin determines the date/time by comparing a specified format against the date/time field(s) in the log file.

For example, an IIS log contains the date in the following form: 2002-11-12 Urchin is able to determine the year, month, and day be using the following format: %Y-%m-%d

Creating A Date/Time Format

To create a custom date/time format, first look at the order and pattern of the date/time data contained in your log file. Then, select from the following Date/Time variables listed below to make up the format. Time zones around the world are expressed as positive and negative offsets of UTC (coordinated universal time).

For example, if your log file contains the time as "07:01:47", then you need to create a pattern to match this. The first thing to note is that the pattern is hours:minutes:seconds. Looking at the variable list below, you will note that %H is the variable for hours, %M is the variable for minutes, and %S is the varialble for seconds. Putting these together yields a format of "%H:%M:%S". If you have a literal '%' character in the date or time format field, you can specify the literal % as %%.

The most common variables are: %Y, %m, %d, %H, %M, and %S.

Date/Time Variable Definitions

  • %A = national representation of the full weekday name.
  • %a = national representation of the abbreviated weekday name.
  • %B = national representation of the full month name.
  • %b = national representation of the abbreviated month name.
  • %d = the day of the month as a decimal number (01-31).
  • %e = the day of month as a decimal number (1-31); single digits are preceded by a blank.
  • %H = the hour (24-hour clock) as a decimal number (00-23).
  • %I = the hour (12-hour clock) as a decimal number (01-12).
  • %j = the day of the year as a decimal number (001-366).
  • %k = the hour (24-hour clock) as a decimal number (0-23); single digits are preceded by a blank.
  • %l = the hour (12-hour clock) as a decimal number (1-12); single digits are preceded by a blank.
  • %M = the minute as a decimal number (00-59).
  • %m = the month as a decimal number (01-12).
  • %p = national representation of either "ante meridiem" or "post meridiem" as appropriate.
  • %S = the second as a decimal number (00-60).
  • %s = the number of seconds since the Epoch, UTC (see mktime(3)).
  • %w = the weekday (Sunday as the first day of the week) as a decimal number (0-6).
  • %Y = the year with century as a decimal number.
  • %y = the year without century as a decimal number (00-99).
  • %z = the time zone offset from UTC; a leading plus sign stands for east of UTC, a minus sign for west of UTC, hours and minutes follow with two digits each and no delimiter between them (common form for RFC 822 date headers).
  • %% = `%'.