Differences

This shows you the differences between two versions of the page.

--- uls:agents:win_tools:win_eventlog [2013-11-18 17:06]
uls created
+++ uls:agents:win_tools:win_eventlog [2014-12-16 15:05] (current)
uls
@@ Line 1: / Line 1: @@
 ===== win_eventlog =====
-Event Log
+'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.
-``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 ====
-Configuration
-=============
 The configuration file allows customizing of execution parameters.
-See also the annotations in the delivered ``win_eventlog.conf``.
+See also the annotations in the delivered 'win_eventlog.conf'.
 Description in order of appearance:
-IDENTIFIER = _win_eventlog
+<file - win_eventlog.conf>
- There may be more than one instance of win_eventlog running on the same
+# Configuration file for win_eventlog
-  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.
+# Name of the ULS teststep where the script runtime information is found
-  You MUST specify the full path!
+# (that is not the teststep where the events are found, though).
-ULS_SERVER = 10.1.2.3:11975
+IDENTIFIER = _win_eventlog
-  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.
+# Where to place log files and files with intermediate results.
+#
+# You MUST specify the full path!
-  If ULS_SERVER is not set or remarked, no value files will be transferred to ULS.
+WORK_DIRECTORY = C:\temp\win_tools
-  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
+# Name and port of the ULS-Server.
-  from the ULS_DIRECTORY to the ULS-server. Enter the complete path to the
+# If not set, nothing is transferred to ULS from this script.
-  send2uls.exe executable. If not set, nothing is transferred to ULS.
+# But the ULS value files are always placed in the ULS_DIRECTORY
-  But the files are **always** placed in the ULS_DIRECTORY.
+# (So the ULS value files may be processed by another script).
-ULS_HOSTNAME =
+# That is the ULS-server in the test environment
-  All gathered metrics are save on the ULS-server in relation to the
+ULS_SERVER = 10.1.2.3:11975
-  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::
+# -------------------------------------------------------------------
+# Directory, where to write the ULS value files.
-    EVENTLOG_LIST = Application, Security, System
+ULS_DIRECTORY = C:\TEMP\ULS
-    EVENTLOG_LIST = windows powershell
-EVENTLOG_SKIPLIST = <eventlog_1>,<eventlog_2>,...,<eventlog_i>
+# -------------------------------------------------------------------
-  Skip the event entries of the defined event logs.
+# 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!
-  The <eventlog_i> may contain wildcards * and ?, it is tested by using "-match".
+SEND2ULS = C:\admin\win_tools\send2uls.exe
+# SEND2ULS = C:\admin\win_tools\send2uls.exe -S
-  Examples::
-    EVENTLOG_SKIPLIST = Internet Explorer,Microsoft*
+# -------------------------------------------------------------------
+# 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
-TYPE_LIST = <type_1>,<type_2>,...,<type_i>
+# -------------------------------------------------------------------
-  Process all event entries that possess one of these event types.
+# Section to be used in the ULS
-  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.
+ULS_SECTION = Windows
-  Known types are: ERROR, WARNING, INFORMATION, SUCCESS and FAILURE.
-  Example, only process events with types ERROR and WARNING::
+# 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
-    TYPE_LIST = ERROR,WARNING
+# <ULS_HOSTNAME>
+#   <ULS_SECTION>
+#     <ULS_TESTSTEP_LEAD>
+#       <name of eventlog>
+#
+# Example: Check the eventlog "Security" of computer "win5387"
+#
+# win5307
+#   Windows
+#     eventlog
+#       Security
-TYPE_SKIPLIST = <type_1>,<type_2>,...,<type_i>
+# -------------------------------------------------------------------
-  Skip all event entries that possess one of these event types.
+# Settings for checking the eventlogs
-  That can be used mostly **instead** of TYPE_LIST.
-  Example, process all events but not those with type INFORMATION::
-    TYPE_SKIPLIST = INFORMATION
+# 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
-SOURCE_LIST = <source_1>, <source_2>, ...<source_i>
+# EVENTLOG_LIST = windows powershell
-  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::
+# But not these eventlogs.
+# EVENTLOG_SKIPLIST = <eventlog1>,<eventlog2>,...
+# EVENTLOG_SKIPLIST = Internet Explorer,Microsoft-Windows-Forwarding
-    MSSQLSERVER,APCPBEAgent,F-Secure Anti-Virus
+# -------------------------------------------------------------------
+# 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
-SOURCE_SKIPLIST = <source_1>, <source_2>, ...<source_i>
+# But not these types
-  Skip all event entries that possess one of these sources.
+# TYPE_SKIPLIST = <type1>,<type2>,...
-  That can be used mostly **instead** of SOURCE_LIST.
+# TYPE_SKIPLIST = information
-  # 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
+#
+# 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 =
-SOURCE_ID_LIST_xxx = <source_1>,<id_1>
+# Skip any events generally from these sources.
-  Process all event entries that possess these source and id combinations.
+# An empty list means nothing (is skipped), e.g.
-  Only events having one of the defined source and id combinations will be processed further.
+# MSSQLSERVER,APCPBEAgent,F-Secure Anti-Virus
-  An empty list means all event entries.
+#
-  The <source_i> and <id_i> expressions are tested exactly (no wildcards).
+# SOURCE_SKIPLIST = <source1>, <source2>, ...
-  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 + EVENT_ID
-    SOURCE_ID_LIST_030 = <source_3>,<id_3>
+#
-    SOURCE_ID_LIST_040 = <source_4>,<id_4>
+# 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).
+#
-  Examples::
+# SOURCE_ID_LIST_010 = <source1>,<id1>
-    SOURCE_ID_LIST_010 = EventLog,6006
+# SOURCE_ID_LIST_020 =
-    SOURCE_ID_LIST_020 = DCOM,10016
+# ...
+# 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_xxx = <source_1>,<id_1>
+SOURCE_ID_SKIPLIST_010 = Internet Explorer , 1234
-  Skip all event entries that possess these source and id combinations.
+# SOURCE_ID_SKIPLIST_020 = <source1>,<id1>
-  Only events not having one of the defined source and id combinations will be processed further.
+# SOURCE_ID_SKIPLIST_030 = <source2>,<id2>
-  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 + EVENT_ID + MESSAGE
-    SOURCE_ID_SKIPLIST_012 = Internet Explorer , 1234
+#
+# 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_xxx = <source_i>,<id_i>,<text expression_i>
+SOURCE_ID_MESSAGE_SKIPLIST_010 = Service Control Manager,7036,Beendet
-  Skip all event entries that possess these source and id combinations and contains
+SOURCE_ID_MESSAGE_SKIPLIST_015 = TestWinTools, 1111, bbbbb|aaaaa
-  the text expression (may contain wildcards * and ?, case insensitive, tested by using "-match")
+# SOURCE_ID_MESSAGE_SKIPLIST_017 = halali , 111  , jo, man, so ist das
-  within its message. All other events will be processed further.
+# SOURCE_ID_MESSAGE_SKIPLIST_020 = <source1>,<id1>,<text expression1>
-  The <source_i> and <id_i> expressions are tested exactly (no wildcards).
+# SOURCE_ID_MESSAGE_SKIPLIST_030 = <source2>,<id2>,<text expression2>
+# ...
-  **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).
+# Concealing
-  You may specify several <text expression> separated by '|' (pipe) for each source and id combination.
+#
+# 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.
-  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
+# Specify the CONCEAL_FOR time in minutes
-  .. 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 = 60
+# CONCEAL_FOR = 20
-    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
-  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
+# Formatting
-  entry to ULS. Use placeholders which are enclosed by double underscores "__".
+#
-  Each placeholder is replaced by the actual value of the event log entry.
+# EVENT_FORMAT
-  A reasonable default format is used if nothing is specified.
+#
+# 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
-  These are the possible placeholders:
+# 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__
+# -----
-  * __TYPE__
+# TIME_GENERATED_FORMAT
-  * __SOURCE__
+#
-  * __EVENT_ID__
+# Customize the appearance of the date and time within the EVENT_FORMAT.
-  * __MESSAGE__
+# The conversion of the date and time is done in PS by using:
-  * __USERNAME__
+# get-date -format $time_generated_format $event_log_entry.TimeGenerated
-  * __CATEGORY__
-  * __NL__ specifies a newline
-  Example::
+#                      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)
-    EVENT_FORMAT = __TIME_GENERATED__ __TYPE__, Source: __SOURCE__, ID: __EVENT_ID__: __NL____MESSAGE__
+# TIME_GENERATED_FORMAT = dd.MM.yyyy HH:mm:ss
+</file>
-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:
+==== Usage ====
-  .. ??? looks as if powershell is not yet supported on my installed Pygments
+-----
-  .. code-block:: bash
+=== Manually ===
-    $result = get-date -format $time_generated_format $event_log_entry.TimeGenerated
+You can start the 'win_eventlog' manually as any user (although you may
-  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
+<code winbatch win_eventlog.bat>
+C:\> cd C:\ADMIN\WIN_TOOLS\
-  C:\> cd C:\ADMIN\WIN_TOOLS\
+C:\ADMIN\WIN_TOOLS> win_eventlog.bat
-  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
+defined as WORKING_DIR in the 'win_eventlog.conf', the default is 'C:\TEMP\WIN_TOOLS'.
-is ``C:\TEMP\WIN_TOOLS``.
+-----
-Regular Execution
+=== Regular Execution ===
------------------
-Use Scheduled Tasks and activate the script ``C:\ADMIN\WIN_TOOLS\win_eventlog.bat``
+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
+==== Gathered Metrics ====
-================
+-----
+=== eventlog ===
-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.
+defined and filtered event logs. The 'System' event log is taken as an example here.
-System
+== 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:
+{|
+! 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:
 -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
+ For re-occurring events with the same source-id-combinations are aggregated and get an additional line (prepended) like:
-  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.
+|}
-  Which means that this event has been found 3 times in the time period
+== _win_eventlog ==
-  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
+Meta information to the execution of the monitoring script. Note that the name may differ because it is configurable in the 'win_eventlog.conf'.
-  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.
+! 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.
+|}
-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.

Universal Logging System

User Tools

Site Tools

Differences

Page Tools