Win32 Event Log

Supported OS Windows

Integration version2.13.2

Overview

The Win32 Event Log check watches for Windows Event Logs and forwards them to Datadog.

Enable this check to:

  • Track system and application events in Datadog.
  • Correlate system and application events with the rest of your application.

For more information, see the Windows Event Logging documentation.

Setup

Installation

The Windows Event Log check is included in the Datadog Agent package. There is no additional installation required.

Configuration

Windows Event Logs can be collected as one or both of the following methods.

Both methods are configured in win32_event_log.d/conf.yaml in the conf.d/ folder at the root of your Agent’s configuration directory. See the sample win32_event_log.d/conf.yaml for all available configuration options.

List Windows Event channels

First, identify the Windows Event Log channels you want to monitor.

Depending on collection method, the channel name can be used for the following configuration parameters:

  • Datadog Logs: channel_path
  • Datadog Events: path
  • Datadog Events (legacy): log_file
PowerShell

To see a list of channels, run the following command in PowerShell:

Get-WinEvent -ListLog *

To see the most active channels, run the following command in PowerShell:

Get-WinEvent -ListLog * | sort RecordCount -Descending

This command displays channels in the format LogMode MaximumSizeInBytes RecordCount LogName.

Example response:

LogMode  MaximumSizeInBytes RecordCount LogName 
Circular          134217728      249896 Security
Circular            5242880        2932 <CHANNEL_2>

The value under the column LogName is the name of the channel. In the example above, the channel name is Security.

Windows Event Viewer

To find the channel name for an Event Log in the Windows Event Viewer, open the Event Log Properties window and refer to the Full Name field. In the following example, the channel name is Microsoft-Windows-Windows Defender/Operational.

Windows Event Log

Event collection

To collect Windows Event Logs as Datadog events, configure channels under the instances: section of your win32_event_log.d/conf.yaml configuration file.

The Datadog Agent can be configured to collect Windows Event Logs as Datadog events in two ways. Each method has its own configuration syntax for channels and for filters (see Filtering Events).

  • The latest method uses the Event Log API. Datadog recommends using the Event Log API because it has better performance than the legacy method below.


    To use the Event Log API collection method, set legacy_mode: false in each instance. If legacy_mode: false is set, the path is required to be set in the \win32_event_log.d\conf.yaml file.


    This example shows entries for the Security and <CHANNEL_2> channels:

    init_config:
    instances:
      - # Event Log API 
        path: Security
        legacy_mode: false
        filters: {}
    
      - path: "<CHANNEL_2>" 
        legacy_mode: false
        filters: {}
    
  • The legacy method uses WMI and is the default mode for an instance.


    If legacy_mode is not set or set to true, then at least one of the following filters must be set: source_name, event_id, message_filters, log_file, or type.


    This example shows entries for the Security and <CHANNEL_2> channels:

    init_config:
    instances:
      - # WMI (default)
        legacy_mode: true
        log_file:
          - Security
    
      - legacy_mode: true
        log_file:
          - "<CHANNEL_2>"
    

    For more information, see Add event log files to the Win32_NTLogEvent WMI class.

Log collection

Available for Agent versions 6.0 or later

Log collection is disabled by default in the Datadog Agent. To collect Windows Event Logs as Datadog logs, activate log collection by setting logs_enabled: true in your datadog.yaml file.

To collect Windows Event Logs as Datadog logs, configure channels under the logs: section of your win32_event_log.d/conf.yaml configuration file. This example shows entries for the Security and <CHANNEL_2> channels:

logs:
  - type: windows_event
    channel_path: Security
    source: windows.events
    service: Windows

  - type: windows_event
    channel_path: "<CHANNEL_2>"
    source: windows.events
    service: myservice

Set the corresponding source parameter to windows.events to benefit from the integration automatic processing pipeline.

Edit the <CHANNEL_2> parameters with the Windows channel name you want to collect events from.

Finally, restart the Agent.

Note: For the Security logs channel, add your Datadog Agent user to the Event Log Readers user group.

Filtering events

Configure one or more filters for the event log. A filter allows you to choose what log events you want to get into Datadog.

Use the Windows Event Viewer GUI to list all the event logs available for capture with this integration.

To determine the exact values, set your filters to use the following PowerShell command:

Get-WmiObject -Class Win32_NTLogEvent

For example, to see the latest event logged in the Security log file, use the following:

Get-WmiObject -Class Win32_NTLogEvent -Filter "LogFile='Security'" | select -First 1

The values listed in the output of the command can be set in win32_event_log.d/conf.yaml to capture the same kind of events.

The information given by the Get-EventLog PowerShell command or the Windows Event ViewerGUI may slightly differ from Get-WmiObject.
Double check your filters' values with Get-WmiObject if the integration does not capture the events you set up.

The Datadog Agent can be configured to collect Windows Event Logs as Datadog events in two ways. Each method has its own configuration syntax for filters. See the sample win32_event_log.d/conf.yaml for all available filter options for respective modes.

Datadog recommends using the latest method for filters.

  • The latest method includes the following filters:

    • path: Application, System, Setup, Security
    • type: Critical, Error, Warning, Information, Success Audit, Failure Audit
    • source: Any available source name
    • id: event_id: Windows EventLog ID

    This example filter uses the latest method.

    instances:
      - legacy_mode: false
        path: System
        filters:
          source:
          - Microsoft-Windows-Ntfs
          - Service Control Manager
          type:
          - Error
          - Warning
          - Information
          - Success Audit
          - Failure Audit
          id:
          - 7036
    

The legacy method is the default mode for filters.

  • The legacy method includes the following filters:

    • log_file: Application, System, Setup, Security
    • type: Critical, Error, Warning, Information, Audit Success, Audit Failure
    • source_name: Any available source name
    • event_id: Windows EventLog ID

    This example filter uses the legacy method.

    instances:
      # Default
      # The following captures errors and warnings from SQL Server which
      # puts all events under the MSSQLSERVER source and tag them with #sqlserver.
      - tags:
          - sqlserver
        type:
          - Warning
          - Error
        log_file:
          - Application
        source_name:
          - MSSQLSERVER
    
      # This instance captures all system errors and tags them with #system.
      - tags:
          - system
        type:
          - Error
        log_file:
          - System
    

For each filter, add a log processing rule in the configuration file at win32_event_log.d/conf.yaml.

Some example filters include the following:

  - type: windows_event
    channel_path: Security
    source: windows.events
    service: Windows       
    log_processing_rules:
    - type: include_at_match
      name: relevant_security_events
      pattern: '"EventID":(?:{"value":)?"(1102|4624|4625|4634|4648|4728|4732|4735|4737|4740|4755|4756)"'

  - type: windows_event
    channel_path: Security
    source: windows.events
    service: Windows       
    log_processing_rules:
    - type: exclude_at_match
      name: relevant_security_events
      pattern: '"EventID":(?:{"value":)?"(1102|4624)"'

  - type: windows_event
    channel_path: System
    source: windows.events
    service: Windows       
    log_processing_rules:
    - type: include_at_match
      name: system_errors_and_warnings
      pattern: '"level":"((?i)warning|error)"'

  - type: windows_event
    channel_path: Application
    source: windows.events
    service: Windows       
    log_processing_rules:
    - type: include_at_match
      name: application_errors_and_warnings
      pattern: '"level":"((?i)warning|error)"'

Here is an example regex pattern to only collect Windows Events Logs from a certain EventID:

logs:
  - type: windows_event
    channel_path: Security
    source: windows.event
    service: Windows
    log_processing_rules:
      - type: include_at_match
        name: include_x01
        pattern: '"EventID":(?:{"value":)?"(101|201|301)"'

Note: The pattern may vary based on the format of the logs. The Agent stream-logs subcommand can be used to view this format.

For more examples of filtering logs, see the Advanced Log Collection documentation.

Legacy events

Applies to Agent versions < 7.41

Legacy Provider EventIDs have a Qualifiers attribute that changes the format of the log, as seen in the Windows Event Schema. These events have the following XML format, visible in Windows Event Viewer:

<EventID Qualifiers="16384">3</EventID>

The following regex must be used to match these EventIDs:

logs:
  - type: windows_event
    channel_path: Security
    source: windows.event
    service: Windows
    log_processing_rules:
      - type: include_at_match
        name: include_legacy_x01
        pattern: '"EventID":(?:{"value":)?"(101|201|301)"'

Agent versions 7.41 or later normalize the EventID field. This removes the need for the substring, (?:{"value":)?, from legacy pattern as it is no longer applicable. A shorter regex pattern can be used from versions 7.41 or later as seen below:

logs:
  - type: windows_event
    channel_path: Security
    source: windows.event
    service: Windows
    log_processing_rules:
      - type: include_at_match
        name: include_x01
        pattern: '"EventID":"(101|201|301)"'

When you’re done setting up filters, restart the Agent using the Agent Manager, or restart the service.

Validation

Check the info page in the Datadog Agent Manager or run the Agent’s status subcommand and look for win32_event_log under the Checks section.

It should display a section similar to the following:

Checks
======

  [...]

  win32_event_log
  ---------------
      - instance #0 [OK]
      - Collected 0 metrics, 2 events & 1 service check

Check the info page in the Datadog Agent Manager or run the Agent’s status subcommand and look for win32_event_log under the Logs Agent section.

It should display a section similar to the following:

Logs Agent
==========

  [...]

  win32_event_log
  ---------------
    - Type: windows_event
      ChannelPath: System
      Status: OK

Data Collected

Metrics

The Win32 Event log check does not include any metrics.

Events

All Windows events are forwarded to Datadog.

Service Checks

The Win32 Event log check does not include any service checks.

Troubleshooting

Need help? Contact Datadog support.

Further Reading

Additional helpful documentation, links, and articles: