> For the complete documentation index, see [llms.txt](https://docs.bindplane.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bindplane.com/integrations/sources/windows-event-forwarding.md). # Windows Event Forwarding Reads events that other Windows hosts forward to a Windows Event Collector (WEC), collected from the local `ForwardedEvents` channel via the OpenTelemetry `windows_event_log` receiver. The source can stream events as they arrive (event-driven) or poll the channel on a fixed interval, and can resolve Security Identifiers (SIDs) to readable account names. This source is Windows-only and runs on the collector host acting as the event collector. ### Supported Telemetry | Platform | Metrics | Logs | Traces | | -------- | ------- | ---- | ------ | | Windows | | ✓ | | ### Prerequisites * The collector must run on a Windows host that is configured as a Windows Event Collector (WEC). * A Windows Event Forwarding (WEF) subscription must already be configured so that source hosts forward their events to this collector. See Microsoft's [Windows Event Collector](https://learn.microsoft.com/en-us/windows/win32/wec/windows-event-collector) documentation and the [source-initiated subscription](https://learn.microsoft.com/en-us/windows/win32/wec/setting-up-a-source-initiated-subscription) setup guide. * Forwarded events must be arriving in the local `ForwardedEvents` channel. This source reads only that channel. ### Configuration
Bindplane docs - Windows Event Forwarding - image 1
**Collection** | Parameter | Type | Required | Default | Description | | ---------------- | ---------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Collection Mode | Toggle (Streaming / Polling) | No | Streaming | Choose between polling the channel on an interval or streaming events as they arrive. Streaming is event-driven with low latency; Polling checks for new events on a fixed interval. | | Polling Interval | Float | No | 0.1 | The interval (seconds) at which the channel is checked for new log entries. Only shown when Collection Mode is Polling. | | Wait Timeout | Float | No | 5 | Maximum duration (seconds) to wait for new events before performing a safety-net poll. Only shown when Collection Mode is Streaming. | **SID Resolution** | Parameter | Type | Required | Default | Description | | ------------------------ | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Enable SID Resolution | Boolean | No | false | When enabled, SIDs in Windows events are automatically resolved to user and group names using the Windows LSA API. Only available when the collector runs on Windows. | | Cache Size | Integer | No | 10000 | Maximum number of SID-to-name mappings to cache in memory (min 100, max 100000). Higher values reduce API calls but increase memory usage (\~100 bytes per entry). Only shown when SID Resolution is enabled. | | Cache Time-To-Live (TTL) | String | No | 15m | How long SID mappings remain valid in cache before being re-resolved. A duration string (e.g., 15m, 1h, 30s). Only shown when SID Resolution is enabled. | **Advanced** | Parameter | Type | Required | Default | Description | | --------------------------- | -------------------- | -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Start At | Enum: beginning, end | No | end | Start reading logs from `beginning` or `end`. | | Raw Logs | Boolean | No | true | When enabled, the XML log is not parsed into a structure but instead saved to the log body. | | Suppress Rendering Info | Boolean | No | true | When enabled, the source will not attempt to resolve rendering info. This can improve performance but comes at a cost of losing some details in the event log. | | Event Data Format | Enum: map, array | No | map | Sets the format used to express Event Data in the parsed log body. Only shown when Raw Logs is disabled. | | Ignore Channel Errors | Boolean | No | true | When enabled, prevents shutdown of the collector when failing to open channels, and instead logs a warning. | | Include Log Record Original | Boolean | No | true | When enabled, the original log record is included in the log body. | | Enable File Offset Storage | Boolean | No | true | When enabled, the current position in the Windows Events is saved to disk, and reading resumes from where it left off after a collector restart. | | Offset Storage Directory | String | No | ${OIQ\_OTEL\_COLLECTOR\_HOME}/storage | The directory that the offset storage file will be created in. Only shown when File Offset Storage is enabled. | | Enable Retry on Failure | Boolean | No | true | Attempt to resend telemetry data that has failed to be transmitted to the destination. | | Initial Interval | Integer | No | 1 | Time (in seconds) to wait after the first failure before retrying. Only shown when Retry on Failure is enabled. | | Max Interval | Integer | No | 30 | The upper bound (in seconds) on backoff. Only shown when Retry on Failure is enabled. | | Max Elapsed Time | Integer | No | 300 | The maximum amount of time (in seconds) spent trying to send a batch, used to avoid a never-ending retry loop. Only shown when Retry on Failure is enabled. | ### Examples #### Stream forwarded events with SID resolution Collect the `ForwardedEvents` channel in streaming mode and resolve SIDs to account names. Raw logs are disabled so events are parsed into structured fields. ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: windows-event-forwarding spec: type: windowseventforwarding parameters: - name: use_polling_collection_mode value: false - name: wait_timeout value: 5 - name: raw_logs value: false - name: event_data_format value: map - name: resolve_sids_enabled value: true - name: resolve_sids_cache_size value: 10000 - name: resolve_sids_cache_ttl value: 15m ``` ### Configuration Tips * Streaming mode (the default) delivers events with low latency and uses Wait Timeout as a safety-net poll. Switch to Polling mode and tune Polling Interval if you need fixed-interval collection. * SID resolution requires the collector to run on Windows. Common well-known SIDs are resolved locally; other SIDs are resolved via the Windows LSA API, which contacts the domain controller for domain-joined machines. * Leave File Offset Storage enabled so the collector resumes from its last position after a restart instead of re-reading or skipping events. ### Troubleshooting #### No events are collected Symptoms: the source is healthy but produces no logs. Solutions: 1. Confirm the host is a Windows Event Collector and a WEF subscription is active and forwarding to it. 2. Verify events are present in the local `ForwardedEvents` channel (open Event Viewer on the collector host). 3. If you expect previously stored events, set Start At to `beginning`. #### Collector fails to start or logs channel errors Symptoms: the collector errors when opening the channel, or logs channel warnings. Solutions: 1. Ensure the `ForwardedEvents` channel exists and the collector service account can read it. 2. Ignore Channel Errors is enabled by default, which logs a warning instead of shutting down. Disable it only if you want channel-open failures to be fatal. #### SIDs are not resolved to account names Symptoms: events still contain raw SID values (e.g., `S-1-5-...`). Solutions: 1. Confirm Enable SID Resolution is on and the collector is running on Windows. 2. For domain SIDs, ensure the collector host can reach a domain controller. Unresolvable SIDs are preserved as-is and no events are dropped. ### Standalone Source ```yaml apiVersion: bindplane.observiq.com/v1 kind: Source metadata: name: windows-event-forwarding spec: type: windowseventforwarding parameters: - name: start_at value: end - name: use_polling_collection_mode value: false - name: wait_timeout value: 5 - name: resolve_sids_enabled value: false - name: raw_logs value: true - name: suppress_rendering_info value: true - name: ignore_channel_errors value: true - name: include_log_record_original value: true - name: enable_offset_storage value: true - name: offset_storage_dir value: ${OIQ_OTEL_COLLECTOR_HOME}/storage - name: retry_on_failure_enabled value: true ``` ### Related Resources * [Windows Event Log Receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/windowseventlogreceiver/README.md) — the upstream OpenTelemetry receiver this source configures. * [Windows Event Collector](https://learn.microsoft.com/en-us/windows/win32/wec/windows-event-collector) — Microsoft documentation for the event collector and WEF subscriptions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bindplane.com/integrations/sources/windows-event-forwarding.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.