Windowseventlog Receiver

Available in: contrib Maintainers: @mrsillydog, @pjanotti Source: opentelemetry-collector-contrib

Supported Telemetry

Overview

Configuration Fields

Field	Default	Description
`channel`	required	The windows event log channel to monitor
`ignore_channel_errors`	false	If true, Prevents shutdown of collector when failing to open event log channels and instead logs a warning
`max_reads`	100	The maximum number of records read into memory, before beginning a new batch
`start_at`	`end`	On first startup, where to start reading logs from the API. Options are `beginning` or `end`
`poll_interval`	1s	The interval at which the channel is checked for new log entries. This check begins again after all new bodies have been read. Only used when event-driven scraping is disabled (see `event_driven_scraping` below).
`max_events_per_poll`	0	The maximum number of events allowed to be read per polling interval, see `poll_interval`. Zero means that there is no limit and the receiver will consume all events available. Ignored when event-driven scraping is enabled.
`wait_timeout`	5s	Maximum duration to wait for new events before performing a safety-net poll. Only used when event-driven scraping is enabled.
`event_driven_scraping`	false	If `true`, the receiver wakes on Windows API signals instead of polling on a fixed interval, reducing latency and avoiding unnecessary wakeups between events. Use `wait_timeout` to configure the safety-net poll interval. This option has the same effect as enabling the `stanza.windows.eventDrivenScraping` feature gate; event-driven scraping is used when either is set. This configuration option should be treated as experimental until the feature gate has been promoted from alpha stability.
`attributes`	{}	A map of `key: value` pairs to add to the entry’s attributes. Keys must be strings, values must be strings or expressions that evaluate to a string.
`resource`	{}	A map of `key: value` pairs to add to the entry’s resource. Keys must be strings, values must be strings or expressions that evaluate to a string.
`operators`	[]	An array of operators. See below for more details
`raw`	false	If false, the body of emitted log records will contain a structured representation of the event. Otherwise, the body will be the original XML string.
`event_data_format`	`map`	Controls the structure of the `event_data` field when `raw` is false. `map` emits a flat map (named elements as direct keys, anonymous elements as `param1`, `param2`, etc.). `array` emits the legacy format with a nested `data` array of single-key maps.
`include_log_record_original`	false	If false, no additional attributes are added. If true, `log.record.original` is added to the attributes, which stores the original XML string according to the configured `suppress_rendering_info` (see below).
`suppress_rendering_info`	false	If false, additional syscalls may be made to retrieve detailed information about the event. Otherwise, some unresolved values may be present in the event.
`exclude_providers`	[]	One or more event log providers to exclude from processing.
`storage`	none	The ID of a storage extension to be used to store bookmarks. Bookmarks allow the receiver to pick up where it left off in the case of a collector restart. If no storage extension is used, the receiver will manage bookmarks in memory only.
`retry_on_failure.enabled`	`false`	If `true`, the receiver will pause reading a file and attempt to resend the current batch of logs if it encounters an error from downstream components.
`retry_on_failure.initial_interval`	`1 second`	Time to wait after the first failure before retrying.
`retry_on_failure.max_interval`	`30 seconds`	Upper bound on retry backoff interval. Once this value is reached the delay between consecutive retries will remain constant at the specified value.
`retry_on_failure.max_elapsed_time`	`5 minutes`	Maximum amount of time (including retries) spent trying to send a logs batch to a downstream consumer. Once this value is reached, the data is discarded. Retrying never stops if set to `0`.
`remote`	object	Remote configuration for connecting to a remote machine to collect logs. Includes server (the address of the remote server), with username, password, and optional domain.
`query`	none	XML query used for filtering events. See Query Schema
`path`	none	File path for EVTX file archive to read.
`resolve_sids`	object	Configuration for resolving Windows Security Identifiers (SIDs) to user/group names. See SID Resolution section below.
`resolve_sids.enabled`	`false`	If `true`, automatically resolves SIDs to user and group names in Windows event logs.
`resolve_sids.cache_size`	`10000`	Maximum number of SID-to-name mappings to cache in memory. Older entries are evicted using LRU policy.
`resolve_sids.cache_ttl`	`15m`	Time-to-live for cached SID mappings. After this duration, SIDs will be re-resolved from the Windows LSA API.
`discover_domain_controllers`	`false`	Automatically discover and collect events from Active Directory domain controllers.

Feature Gates

Feature Gate	Stage	Description
`stanza.windows.eventDrivenScraping`	Alpha	When enabled, the receiver wakes on Windows API signals instead of polling on a fixed interval, reducing latency and avoiding unnecessary wakeups between events. Use `wait_timeout` to configure the safety-net poll interval.

Operators

Each operator performs a simple responsibility, such as parsing a timestamp or JSON. Chain together operators to process logs into a desired format.

Every operator has a type.
Every operator can be given a unique id. If you use the same type of operator more than once in a pipeline, you must specify an id. Otherwise, the id defaults to the value of type.
Operators will output to the next operator in the pipeline. The last operator in the pipeline will emit from the receiver. Optionally, the output parameter can be used to specify the id of another operator to which logs will be passed directly.
Only parsers and general purpose operators should be used.

Additional Terminology and Features

An entry is the base representation of log data as it moves through a pipeline. All operators either create, modify, or consume entries.
A field is used to reference values in an entry.
A common expression syntax is used in several operators. For example, expressions can be used to filter or route entries.
timestamp parsing is available as a block within all parser operators, and also as a standalone operator. Many common timestamp layouts are supported.
severity parsing is available as a block within all parser operators, and also as a standalone operator. Stanza uses a flexible severity representation which is automatically interpreted by the stanza receiver.

Example Configurations

Simple

Configuration:

receivers:
    windows_event_log:
        channel: application

The deprecated component type windowseventlog is still accepted:

receivers:
    windowseventlog:
        channel: application

Output entry sample:

{
    "channel": "Application",
    "computer": "computer name",
    "event_id":
    {
        "id": 10,
        "qualifiers": 0
    },
    "event_data":
    {
        "ProcessId": "7924",
        "Application": "app.exe"
    },
    "keywords": ["Classic"],
    "level": "Information",
    "message": "Test log",
    "opcode": "Info",
    "provider":
    {
        "event_source": "",
        "guid": "",
        "name": "otel"
    },
    "record_id": 12345,
    "rendering_info":
    {
        "channel": "Application",
        "culture": "en-US",
        "keywords": ["Classic"],
        "level": "Information",
        "message": "Test log",
        "opcode": "Info",
        "provider": "otel",
        "task": ""
    },
    "system_time": "2022-04-15T15:28:08.898974100Z",
    "task": ""
}

The event_data field format is controlled by the event_data_format setting: event_data_format: map (default) — Named <Data> elements become direct keys (e.g., event_data.ProcessId). Anonymous <Data> elements (without a Name attribute) use numbered keys: param1, param2, etc. Fields are directly accessible via OTTL: body["event_data"]["ProcessId"]. event_data_format: array — Preserves the legacy format where data is stored as a nested data array of single-key maps:

{
    "event_data": {
        "data": [
            {"ProcessId": "7924"},
            {"Application": "app.exe"}
        ]
    }
}

The rendering_info key is populated when suppress_rendering_info is false (the default). It contains the human-readable strings for level, task, opcode, keywords, message, channel, provider, and culture as rendered by the publisher manifest. The top-level level, task, opcode, and keywords fields are derived from rendering_info when present, falling back to the raw system values otherwise. For events that use UserData instead of EventData (e.g., Security event 1102 — audit log cleared), a user_data key is emitted instead of (or alongside) event_data:

{
    "user_data": {
        "name": "LogFileCleared",
        "data": {
            "SubjectUserName": "SYSTEM",
            "SubjectLogonId": "0x3e7"
        }
    }
}

Remote Configuration

If collection of the local event log is desired, a separate receiver needs to be created. Requirements for Remote Configuration:

The remote computer must enable the “Remote Event Log Management” Windows Firewall exception. Otherwise, when you try to use the session handle, the call will error with RPC_S_SERVER_UNAVAILABLE.
The computer to which you are connecting must be running Windows Vista or later.

Single server configuration:

receivers:
    windows_event_log:
        channel: application
        remote:
            server:   "remote-server"
            username: "user"
            password: "password"
            domain:   "domain"

XML Queries

You can use XML queries to filter events. The query is passed to the query field in the configuration. The provided query must be a valid XML string. See XML Event Queries The following example only forwards logs from the Application from foo or bar providers.

receivers:
  windows_event_log/query:
    query: |
      <QueryList>
        <Query Id="0">
          <Select Path="Application">*[System[Provider[@Name='foo']]]</Select>
          <Select Path="Application">*[System[Provider[@Name='bar']]]</Select>
        </Query>
      </QueryList>

SID Resolution

Windows Event Logs often contain Security Identifiers (SIDs) instead of readable user or group names. The SID resolution feature automatically resolves these SIDs to human-readable names using the Windows Local Security Authority (LSA) API. Key Features:

Automatically enriches Windows events with resolved user and group names
High-performance LRU cache with configurable size and TTL
Resolves well-known SIDs (SYSTEM, LOCAL_SERVICE, etc.) instantly from static map
Works with domain-joined machines to resolve domain users and groups
Non-breaking: original SID values are preserved alongside resolved names

Configuration:

receivers:
  windows_event_log:
    channel: Security
    resolve_sids:
      enabled: true        # Enable SID resolution
      cache_size: 10000    # Cache up to 10,000 SID-to-name mappings
      cache_ttl: 15m       # Re-resolve SIDs after 15 minutes

Without SID Resolution:

{
  "security": {
    "user_id": "S-1-5-21-3623811015-3361044348-30300820-1013"
  },
  "event_data": {
    "SubjectUserSid": "S-1-5-18",
    "TargetUserSid": "S-1-5-21-3623811015-3361044348-30300820-1013"
  }
}

With SID Resolution:

{
  "security": {
    "user_id": "S-1-5-21-3623811015-3361044348-30300820-1013",
    "user_name": "ACME\\jsmith",
    "domain": "ACME",
    "account": "jsmith",
    "account_type": "User"
  },
  "event_data": {
    "SubjectUserSid": "S-1-5-18",
    "SubjectUserSid_Resolved": "NT AUTHORITY\\SYSTEM",
    "SubjectUserSid_Domain": "NT AUTHORITY",
    "SubjectUserSid_Account": "SYSTEM",
    "SubjectUserSid_Type": "WellKnownGroup",
    "TargetUserSid": "S-1-5-21-3623811015-3361044348-30300820-1013",
    "TargetUserSid_Resolved": "ACME\\jsmith",
    "TargetUserSid_Domain": "ACME",
    "TargetUserSid_Account": "jsmith",
    "TargetUserSid_Type": "User"
  }
}

Performance Characteristics:

Cache hit latency: < 1 microsecond
Cache miss latency: < 5 milliseconds (Windows LSA API call)
Expected cache hit rate: > 99% in steady state
Memory usage: ~100 bytes per cached entry
Throughput impact: < 5% with cache enabled

Limitations:

Only resolves SIDs for the local system or the domain the Windows machine is joined to
Cannot resolve SIDs from trusted domains (requires LDAP extension)
Remote collection: SID resolution only works when the collector runs on Windows
Cache lifecycle: Cache is created at receiver start and closed at shutdown

Troubleshooting: If SID resolution is not working as expected:

Check logs for initialization message:

INFO SID resolution enabled {"cache_size": 10000, "cache_ttl": "15m0s"}

Verify the collector is running on Windows: SID resolution only works on Windows operating systems.
Check for resolution errors: Failed SID lookups are logged at DEBUG level:
DEBUG Failed to resolve SID {"sid": "S-1-5-21-...", "error": "..."}
Verify SID format: Only fields ending with “Sid” or named “UserID” are automatically resolved. Custom SID fields may not be detected.

Well-Known SIDs: The following SIDs are resolved instantly from a static map (no API call required):

S-1-5-18 - NT AUTHORITY\SYSTEM
S-1-5-19 - NT AUTHORITY\LOCAL SERVICE
S-1-5-20 - NT AUTHORITY\NETWORK SERVICE
S-1-5-32-544 - BUILTIN\Administrators
S-1-1-0 - Everyone
And 40+ more common Windows SIDs

Configuration

Example Configuration

windows_event_log:
  start_at: end
  channel: application

Last generated: 2026-08-24

​Windowseventlog Receiver

​Supported Telemetry

​Overview

​Configuration Fields

​Feature Gates

​Operators

​Additional Terminology and Features

​Example Configurations

​Simple

​Remote Configuration

​XML Queries

​SID Resolution

​Configuration

​Example Configuration