> ## 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-alpha-red) **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-alpha-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 `` elements become direct keys (e.g., `event_data.ProcessId`). Anonymous `` 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: | ``` #### 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-07-06*