Universal Logging System

Event Log

``win_eventlog`` checks the event logs for new entries and forwards them to the ULS-server. You may apply a variety of filters to drop event entries or to keep specific event entries and drop the others.

Configuration

The configuration file allows customizing of execution parameters. See also the annotations in the delivered ``win_eventlog.conf``. Description in order of appearance:

IDENTIFIER = _win_eventlog There may be more than one instance of win_eventlog running on the same

computer. Use the IDENTIFIER to uniquely distinguish them. It is 
also the name of the teststep in ULS where the script runtime information is found.

WORK_DIRECTORY = C:\\TEMP\\WIN_TOOLS

That is the directory, where log files and work value files are placed.
You MUST specify the full path!

ULS_SERVER = 10.1.2.3:11975

The win_eventlog script generates a value file in the ULS value file format.
That must be transferred to the ULS-server. You must sepecify here the 
IP address and port of the ULS-server.

If ULS_SERVER is not set or remarked, no value files will be transferred to ULS.
But the ULS value files are **always** placed in the ULS_DIRECTORY, regardless 
of whether they will be further processed or not. So that directory may be 
filled up over time.

ULS_DIRECTORY = C:\\TEMP\\ULS

That is the directory, where win_eventlog writes its ULS value files to.

ULS_SEND2ULS = C:\\TEMP\\WIN_TOOLS\\send2uls.exe

send2uls.exe is the W*ndows executable, which transfers all the ULS value files 
from the ULS_DIRECTORY to the ULS-server. Enter the complete path to the 
send2uls.exe executable. If not set, nothing is transferred to ULS.
But the files are **always** placed in the ULS_DIRECTORY.

ULS_HOSTNAME =

All gathered metrics are save on the ULS-server in relation to the 
hostname of the current computer. If you want to use an alternate 
ULS_HOSTNAME instead of the default computer name, you can define 
it here. Remember that you have to define that computer name in the 
ULS administration and define all possible IP addresses for that.
A "virtual" hostname may be useful in cluster environments.
The entry is remarked by default.

ULS_SECTION = Windows

That expression is used as section in ULS.
See the :ref:`uls_overview` for an explanation of what the section is.

EVENTLOG_LIST = <eventlog_1>,<eventlog_2>,…,<eventlog_i>

Process the event entries of the defined event logs.
An empty list means all event logs.

The <eventlog_i> may contain wildcards * and ?, it is tested by using "-match".

Examples::

  EVENTLOG_LIST = Application, Security, System
  EVENTLOG_LIST = windows powershell

EVENTLOG_SKIPLIST = <eventlog_1>,<eventlog_2>,…,<eventlog_i>

Skip the event entries of the defined event logs.

The <eventlog_i> may contain wildcards * and ?, it is tested by using "-match".

Examples::

  EVENTLOG_SKIPLIST = Internet Explorer,Microsoft*

TYPE_LIST = <type_1>,<type_2>,…,<type_i>

Process all event entries that possess one of these event types.
Only events having one of the defined event types will be processed further. 
An empty list means all event entries.

The <type_i> expression is tested exactly (no wildcards) but case insensitive.
Known types are: ERROR, WARNING, INFORMATION, SUCCESS and FAILURE.

Example, only process events with types ERROR and WARNING::

  TYPE_LIST = ERROR,WARNING

TYPE_SKIPLIST = <type_1>,<type_2>,…,<type_i>

Skip all event entries that possess one of these event types.
That can be used mostly **instead** of TYPE_LIST.

Example, process all events but not those with type INFORMATION::

  TYPE_SKIPLIST = INFORMATION

SOURCE_LIST = <source_1>, <source_2>, …<source_i>

Process all event entries that possess one of these sources.
Only events having one of the defined sources will be processed further. 
An empty list means all event entries.

The <source_i> expression is tested exactly (no wildcards).

Example::

  MSSQLSERVER,APCPBEAgent,F-Secure Anti-Virus

SOURCE_SKIPLIST = <source_1>, <source_2>, …<source_i>

Skip all event entries that possess one of these sources.
That can be used mostly **instead** of SOURCE_LIST.

# Skip any events generally from these sources.
# An empty list means nothing (is skipped), e.g.
# MSSQLSERVER,APCPBEAgent,F-Secure Anti-Virus
#
# SOURCE_SKIPLIST = <source1>, <source2>, ...

SOURCE_ID_LIST_xxx = <source_1>,<id_1>

Process all event entries that possess these source and id combinations.
Only events having one of the defined source and id combinations will be processed further. 
An empty list means all event entries. 
The <source_i> and <id_i> expressions are tested exactly (no wildcards).

An arbitrary number of SOURCE_ID_LIST_xxx may be defined, each may only 
contain one source and id combination::

  SOURCE_ID_LIST_010 = <source_1>,<id_1>
  SOURCE_ID_LIST_020 = <source_2>,<id_2>
  SOURCE_ID_LIST_030 = <source_3>,<id_3>
  SOURCE_ID_LIST_040 = <source_4>,<id_4>

Examples::
  SOURCE_ID_LIST_010 = EventLog,6006
  SOURCE_ID_LIST_020 = DCOM,10016

SOURCE_ID_SKIPLIST_xxx = <source_1>,<id_1>

Skip all event entries that possess these source and id combinations.
Only events not having one of the defined source and id combinations will be processed further. 
An empty list means all event entries (that passed SOURCE_ID_LIST_xxx) will be processed further. 
The <source_i> and <id_i> expressions are tested exactly (no wildcards).

Examples::
  SOURCE_ID_SKIPLIST_010 = Service Control Manager, 7035
  SOURCE_ID_SKIPLIST_012 = Internet Explorer , 1234

SOURCE_ID_MESSAGE_SKIPLIST_xxx = <source_i>,<id_i>,<text expression_i>

Skip all event entries that possess these source and id combinations and contains 
the text expression (may contain wildcards * and ?, case insensitive, tested by using "-match") 
within its message. All other events will be processed further. 
The <source_i> and <id_i> expressions are tested exactly (no wildcards).

**Be careful with umlaute in the text expression!!!** Try to find 
matching text expressions by using wildcards.

There must be only **one** definition for the same source and id combination
(the last definition found wins).
You may specify several <text expression> separated by '|' (pipe) for each source and id combination.  

The event entry is skipped if the source and id matches and if the 
following statement returns true:

.. ??? looks as if powershell is not yet supported on my installed Pygments

.. code-block:: bash

  if ( <event_message> -match <text expressionX> )

Examples::

  SOURCE_ID_MESSAGE_SKIPLIST_010 = Service Control Manager,7036,Beendet
  SOURCE_ID_MESSAGE_SKIPLIST_015 = TestWinTools, 1111, bbbbb|aaaaa
  SOURCE_ID_MESSAGE_SKIPLIST_123 = HECI, 2, Engine*started

CONCEAL_FOR = <mins>

What is concealing? Concealing is used to lower the traffic of event entries 
if they appear in bursts, e.g. the same event entry every 5 seconds.
A source and id combination, which has made it through the filters above, 
is sent to ULS at its first occurrance. The following reoccurring equal 
source and id events will be accumulated for a CONCEAL_FOR time. 
The default value is 60 mins.

If no further source and id events have occurred during the conceal time: 

• the concealing for that source and id event is reset

If any further source and id events **do** have occurred: 

• they are accumulated
• a summary is sent to ULS after the CONCEAL_FOR time
• concealing is reset for that source and id event.

BUT REMEMBER: The same source and id combinations may have

different messages! That is **NOT** covered separately. You will 
only get the message of the last source and id event in the summary.

Example::

  CONCEAL_FOR = 20

USE_EVENT_TIMESTAMP = 1

Set this property to 1 if you want to use the timestamp of 
the event entry as timestamp for the value in ULS.
If not set, the current timestamp is used to save all 
accumulated eventlog entries since the last script run to ULS.

EVENT_FORMAT = <expression>

You may format the appearance of the text value which is sent as 
entry to ULS. Use placeholders which are enclosed by double underscores "__".
Each placeholder is replaced by the actual value of the event log entry.
A reasonable default format is used if nothing is specified.

These are the possible placeholders:

• TIME_GENERATED
• TYPE
• SOURCE
• EVENT_ID
• MESSAGE
• USERNAME
• CATEGORY
• NL specifies a newline

Example::

  EVENT_FORMAT = __TIME_GENERATED__ __TYPE__, Source: __SOURCE__, ID: __EVENT_ID__: __NL____MESSAGE__

TIME_GENERATED_FORMAT = yyyy-MM-dd HH:mm:ss

Customize the appearance of the date and time within the EVENT_FORMAT.
The conversion of the date and time is done in PS by using:

.. ??? looks as if powershell is not yet supported on my installed Pygments

.. code-block:: bash

  $result = get-date -format $time_generated_format $event_log_entry.TimeGenerated

You may specify any valid formatting as described for the powershell 
function "get-date -format".

Example::

  TIME_GENERATED_FORMAT = dddd, MMMM dd, yyyy h:mm:ss tt

Usage

Manually

You can start the ``win_eventlog`` manually as any user (although you may need some privileges to access all operating system objects):

.. code-block:: bat

C:\> cd C:\ADMIN\WIN_TOOLS\
C:\ADMIN\WIN_TOOLS> win_eventlog.bat

The log and work value files are placed in directory which is defined as WORKING_DIR in the ``win_eventlog.conf``, the default is ``C:\TEMP\WIN_TOOLS``.

Regular Execution

Use Scheduled Tasks and activate the script ``C:\ADMIN\WIN_TOOLS\win_eventlog.bat`` (or whatever other name or path you have chosen). Have it executed e.g. every 10 mins.

Gathered Metrics

eventlog

This is the only teststep. It has sub-teststeps depending on the number of defined and filtered event logs. The “System” event log is taken as an example here.

System

entry

The entry holds the complete description of the event log entry matching the defined 
EVENT_FORMAT in the ``win_eventlog.conf``. Here is an example:

2012-12-03 10:06:06 Information, Source: Service Control Manager, ID: 7035: 
The Print Spooler service was successfully sent a stop control.

For re-occurring events with the same source-id-combinations are aggregated 
and get an additional line (prepended) like:

(2012-12-03 09:46:06 - 2012-12-03 10:06:06, 3x)

Which means that this event has been found 3 times in the time period 
between 09:46:06 and 10:06:06 on 2012-12-03.

The appearance of entry may differ depending on your definitions 
in the ``win_eventlog.conf`` file.

_win_eventlog

Meta information to the execution of the monitoring script. Note that the name may differ because it is configurable in the ``win_eventlog.conf``.

message

Is "OK" if there have been no errors during execution of the script. 
Else it will hold the error message(s).

script name, version

The name and version of the script.

runtime

The execution time of the script without transfer to ULS.

start-stop

The start and stop timing tuple of the execution time of the script.

warnings

Warnings may appear, e.g. for empty event logs. These can be ignored. 
Event logs may be excluded in the ``win_eventlog.conf`` to get rid of 
these warnings.