> ## Documentation Index
> Fetch the complete documentation index at: https://otel.fyi/llms.txt
> Use this file to discover all available pages before exploring further.

# Windowseventlog

> OpenTelemetry receiver for Windowseventlog

# Windowseventlog Receiver

![Status](https://img.shields.io/badge/status-beta-yellow)

**Available in:** `contrib`

**Maintainers:** [@mrsillydog](https://github.com/mrsillydog), [@pjanotti](https://github.com/pjanotti)

**Source:** [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/windowseventlogreceiver)

## Supported Telemetry

![Logs](https://img.shields.io/badge/logs-beta-blue)

## 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](../../pkg/stanza/docs/types/expression.md) 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](../../pkg/stanza/docs/types/expression.md) that evaluate to a string. |
| `operators` | \[] | An array of [operators](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/operators/README.md#what-operators-are-available). 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](https://learn.microsoft.com/en-us/windows/win32/api/winevt/nf-winevt-evtformatmessage#remarks) 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](https://learn.microsoft.com/en-us/windows/win32/wes/queryschema-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](#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](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/types/entry.md) is the base representation of log data as it moves through a pipeline. All operators either create, modify, or consume entries.
* A [field](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/types/field.md) is used to reference values in an entry.
* A common [expression](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/types/expression.md) syntax is used in several operators. For example, expressions can be used to [filter](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/operators/filter.md) or [route](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/operators/router.md) entries.
* [timestamp](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/types/timestamp.md) parsing is available as a block within all parser operators, and also as a standalone operator. Many common timestamp layouts are supported.
* [severity](https://github.com/open-telemetry/opentelemetry-log-collection/blob/main/docs/types/severity.md) 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:

```yaml theme={null}
receivers:
    windows_event_log:
        channel: application
```

The deprecated component type `windowseventlog` is still accepted:

```yaml theme={null}
receivers:
    windowseventlog:
        channel: application
```

Output entry sample:

```json theme={null}
{
    "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:

```json theme={null}
{
    "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`:

```json theme={null}
{
    "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:

```yaml theme={null}
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](https://learn.microsoft.com/en-us/previous-versions/aa385231\(v=vs.85\)#xml-event-queries)

The following example only forwards logs from the `Application` from `foo` or `bar` providers.

```yaml theme={null}
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>
```

#### Sensitive Data Redaction

Redaction and transform processors can be used to redact sensitive data from Windows Event Logs.
The examples below assume that the Windows Event Log body is structured JSON (raw: false). They can target nested fields such as "event\_data.ProcessId".
Messages in XML format can also be redacted, but field-level targeting is more limited and generally requires either XML-aware parsing or regex-based masking.

Use below example of [redaction processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/processor/redactionprocessor/README.md) to mask sensitive data.

```yaml theme={null}
redaction/windows_sensitive_logs:
 allow_all_keys: true
 summary: silent
 blocked_key_patterns:
   - "guid"
   - "culture"
```

[Transform processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor) can be used for more complex searches like matching nested values only under specific keys.

```yaml theme={null}
transform/mask_windows_fields:
  error_mode: ignore
  log_statements:
    - context: log
  statements:
    - set(body["event_data"]["ProcessId"], "****") where body["event_data"]["ProcessId"] != nil
    - set(body["rendering_info"]["culture"], "****") where body["rendering_info"]["culture"] != nil
```

#### 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:**

```yaml theme={null}
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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

1. **Check logs for initialization message:**
   ```
   INFO SID resolution enabled {"cache_size": 10000, "cache_ttl": "15m0s"}
   ```

2. **Verify the collector is running on Windows:**
   SID resolution only works on Windows operating systems.

3. **Check for resolution errors:**
   Failed SID lookups are logged at DEBUG level:
   ```
   DEBUG Failed to resolve SID {"sid": "S-1-5-21-...", "error": "..."}
   ```

4. **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

```yaml theme={null}
windows_event_log:
  start_at: end
  channel: application
```

***

*Last generated: 2026-10-05*