===== win_eventlog =====

'win_eventlog' checks the event logs for new entries since the last script execution and forwards them to the ULS-server. 
You may apply a variety of filters to ignore event entries or to keep specific event entries and drop 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:

<file - win_eventlog.conf>
# Configuration file for win_eventlog

# -------------------------------------------------------------------
# Name of the ULS teststep where the script runtime information is found
# (that is not the teststep where the events are found, though).

IDENTIFIER = _win_eventlog
  
# -------------------------------------------------------------------
# Where to place log files and files with intermediate results.
#
# You MUST specify the full path!

WORK_DIRECTORY = C:\temp\win_tools


# -------------------------------------------------------------------
# Name and port of the ULS-Server.
# If not set, nothing is transferred to ULS from this script.
# But the ULS value files are always placed in the ULS_DIRECTORY
# (So the ULS value files may be processed by another script).

# That is the ULS-server in the test environment
ULS_SERVER = 10.1.2.3:11975
  
# -------------------------------------------------------------------
# Directory, where to write the ULS value files.

ULS_DIRECTORY = C:\TEMP\ULS

# -------------------------------------------------------------------
# Enter the complete path to the send2uls.exe executable.
# If not set, nothing is transferred to ULS.
# The files are always placed in the ULS_DIRECTORY.
#
# You MUST specify the full path!

SEND2ULS = C:\admin\win_tools\send2uls.exe
# SEND2ULS = C:\admin\win_tools\send2uls.exe -S

# -------------------------------------------------------------------
# The name of the server to be used in ULS 
# You only need to set this, if you have a cluster and 
# you want to use a clustername instead of the real
# computername, which is the default.

#  ULS_HOSTNAME = WINXP123

# -------------------------------------------------------------------
# Section to be used in the ULS 

ULS_SECTION = Windows

# Leading expression for ULS teststep. This expression is shown 
# right below the ULS_SECTION defined above.
# The name of the eventlog is appended, separated by ':'
ULS_TESTSTEP_LEAD = eventlog

# <ULS_HOSTNAME>
#   <ULS_SECTION>
#     <ULS_TESTSTEP_LEAD>
#       <name of eventlog>
#
# Example: Check the eventlog "Security" of computer "win5387"
#
# win5307
#   Windows
#     eventlog
#       Security

# -------------------------------------------------------------------
# Settings for checking the eventlogs


# Filtering
#
# -------------------------------------------------------------------
# EVENTLOG
#
# This is/are the eventlogs to scan. Comma separated.
# An empty list means all available event logs on the machine, 
# except those probably defined in EVENTLOG_SKIPLIST.
#
# The <eventlog_i> may contain wildcards * and ?, it is tested by using -match
#
# EVENTLOG_LIST = <eventlog1>,<eventlog2>,...
# EVENTLOG_LIST = Application, Internet Explorer, Security, System, Windows PowerShell, ...

# EVENTLOG_LIST = Application,System

# EVENTLOG_LIST = windows powershell

# But not these eventlogs.
# EVENTLOG_SKIPLIST = <eventlog1>,<eventlog2>,...
# EVENTLOG_SKIPLIST = Internet Explorer,Microsoft-Windows-Forwarding

# -------------------------------------------------------------------
# TYPE
#
# You can define simple text pattern, comma separated, and only those 
# event log entries that contain these expressions will be sent to the ULS. 
# All <type_i> are checked consecutively.
# All <type_i> matching is done case insensitive.
# The <type_i> expression is tested exactly (no wildcards).

# Only these types, or all if empty.
# ERROR,WARNING,INFORMATION,SUCCESS,FAILURE
# An empty list means everything
# TYPE_LIST = <type1>,<type2>,...
# TYPE_LIST = information ,   error

# But not these types
# TYPE_SKIPLIST = <type1>,<type2>,...
# TYPE_SKIPLIST = information


# -------------------------------------------------------------------
# SOURCE
#
# The <source_i> expression is tested exactly (no wildcards).
#
# Process these sources, or all if empty, e.g.
# MSSQLSERVER,APCPBEAgent,F-Secure Anti-Virus
#
# An empty list means everything
# SOURCE_LIST = <source1>, <source2>, ...
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 + EVENT_ID
#
# Only! these source and event-id combinations are processed, 
# or all if empty. So, if you define any here, then any 
# defined SOURCE_ID_LIST_* have no effect.
#
# The <source_i> and <id_i> expressions are tested exactly (no wildcards).
#

# SOURCE_ID_LIST_010 = <source1>,<id1>
# SOURCE_ID_LIST_020 =
# ...

# List one or many combinations of sources and event IDs that are to be ignored.
# Event IDs may appear for different sources, so specify always the combination
# of source AND event ID.

SOURCE_ID_SKIPLIST_010 = Internet Explorer , 1234
# SOURCE_ID_SKIPLIST_020 = <source1>,<id1>
# SOURCE_ID_SKIPLIST_030 = <source2>,<id2>
# ...

# -------------------------------------------------------------------
# SOURCE + EVENT_ID + MESSAGE
#
# Skip entries with matching combination of SOURCE, EVENT_ID, and a 
# simple (not regular) text expression, case insensitive and may 
# contain wildcards, within MESSAGE. 
# There must only be ONE definition for the same source and event_id combination. 
# You may specify several <text expression> separated by a '|' (pipe).
#
# Be generally careful with umlaute!!!
#
# The <sourceX> and <idX> expressions are tested exactly (no wildcards).
# The <text expressionX> expression may contain wildcards * and ?, 
# it is tested by using '-match'.
#
# The event entry is skipped if an 
#   if ( <event_message> -match <text expressionX> ) is true.
#
# SOURCE_ID_MESSAGE_SKIPLIST_xxx = <sourceX>,<idX>,<text expressionX>


SOURCE_ID_MESSAGE_SKIPLIST_010 = Service Control Manager,7036,Beendet
SOURCE_ID_MESSAGE_SKIPLIST_015 = TestWinTools, 1111, bbbbb|aaaaa
# SOURCE_ID_MESSAGE_SKIPLIST_017 = halali , 111  , jo, man, so ist das
# SOURCE_ID_MESSAGE_SKIPLIST_020 = <source1>,<id1>,<text expression1>
# SOURCE_ID_MESSAGE_SKIPLIST_030 = <source2>,<id2>,<text expression2>
# ...

# -------------------------------------------------------------------
# Concealing
#
# concealing of event entry bursts:
# A source+id combination, which has made it through the filters above, 
# is sent to ULS at its first occurrance. The following reoccurring equal 
# source+id events will be accumulated for a CONCEAL_FOR time. 
# If no further source+id events have occurred during the conceal time: 
#   the concealing for that source+id event is reset
# If any further source+id events do have occurred: 
#   they are accumulated and
#   a summary is sent to ULS after the CONCEAL_FOR time and 
#   concealing is reset for that source+id event.
#
# BUT REMEMBER: The same source and event-id combinations may have 
# different messages! They are NOT covered separately. You will 
# only get the message of the last source+id event in the summary.


# Specify the CONCEAL_FOR time in minutes

CONCEAL_FOR = 60
# CONCEAL_FOR = 20


# -------------------------------------------------------------------
# Timestamp evaluation
#
# 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 
# eventlog entries to ULS.

USE_EVENT_TIMESTAMP = 1


# -------------------------------------------------------------------
# Formatting
# 
# EVENT_FORMAT
#
# If no formatting is defined, a default will be used.
# These are the placeholders:
# __TYPE__     __SOURCE__    __EVENT_ID__  __TIME_GENERATED__
# __MESSAGE__  __USERNAME__  __CATEGORY__  __NL__
#
# Use __NL__ to specify a newline

# EVENT_FORMAT = __TIME_GENERATED__ __TYPE__, Quelle: __SOURCE__, ID: __EVENT_ID__: __NL____MESSAGE____NL__-----
EVENT_FORMAT = __TIME_GENERATED__ __TYPE__, Quelle: __SOURCE__, ID: __EVENT_ID__: __NL____MESSAGE__

# -----
# TIME_GENERATED_FORMAT
#
# 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:
# get-date -format $time_generated_format $event_log_entry.TimeGenerated

#                      format                          example
# Default (iso-like) : yyyy-MM-dd HH:mm:ss            (2013-06-13 19:23:17)
# FullDateTimePattern: dddd, MMMM dd, yyyy h:mm:ss tt (Monday, May 28, 2012 11:35:00 AM)
# German             : dd.MM.yyyy HH:mm:ss            (13.06.2013 19:23:17)

# TIME_GENERATED_FORMAT = dd.MM.yyyy HH:mm:ss

</file>

-----

==== 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 winbatch win_eventlog.bat>
C:\> cd C:\ADMIN\WIN_TOOLS\
C:\ADMIN\WIN_TOOLS> win_eventlog.bat
</code>

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 ==

{|
! teststep
! description
|-
| 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'.

{|
! teststep
! description
|-
| 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.
|}

-----