windowseventlogreceiver

README

Windows Event Log Receiver

This receiver tails and parses logs from windows event log API using the opentelemetry-log-collection library.

Status
Stability	alpha: logs
Unsupported Platforms	darwin, linux
Distributions	contrib
Issues
Code coverage
Code Owners	@armstrmi, @pjanotti

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 the stanza.windows.eventDrivenScraping feature gate is disabled.
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 the stanza.windows.eventDrivenScraping feature gate is enabled.
wait_timeout	5s	Maximum duration to wait for new events before performing a safety-net poll. Only used when the stanza.windows.eventDrivenScraping feature gate is enabled.
attributes	{}	A map of key: value pairs to add to the entry's attributes.
resource	{}	A map of key: value pairs to add to the entry's resource.
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
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:

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

Documentation

Overview

Package stanzareceiver implements a receiver that can be used by the OpenTelemetry collector to receive logs using the stanza log agent

Index

• func NewFactory() receiver.Factory
• type ResolveSIDsConfig
  • func (c *ResolveSIDsConfig) Validate() error
• type WindowsLogConfig

Functions

func NewFactory

func NewFactory() receiver.Factory

NewFactory creates a factory for the Windows Event Log receiver.

Types

type ResolveSIDsConfig

type ResolveSIDsConfig struct {
	// Enabled controls whether SID resolution is active
	Enabled bool `mapstructure:"enabled"`

	// CacheSize is the maximum number of SIDs to cache (LRU eviction)
	// Default: 10000
	CacheSize uint `mapstructure:"cache_size"`

	// CacheTTL is how long cache entries remain valid
	// Default: 15m
	CacheTTL time.Duration `mapstructure:"cache_ttl"`
}

ResolveSIDsConfig contains configuration for SID resolution

func (*ResolveSIDsConfig) Validate

func (c *ResolveSIDsConfig) Validate() error

Validate checks if the configuration is valid

type WindowsLogConfig

type WindowsLogConfig struct {
	InputConfig        windows.Config `mapstructure:",squash"`
	adapter.BaseConfig `mapstructure:",squash"`

	// ResolveSIDs contains configuration for SID-to-username resolution
	ResolveSIDs ResolveSIDsConfig `mapstructure:"resolve_sids"`

	// DiscoverDomainControllers controls whether to attempt auto-discovery of domain controllers for joined machines with remote credentials
	DiscoverDomainControllers bool `mapstructure:"discover_domain_controllers"`
	// contains filtered or unexported fields
}

WindowsLogConfig defines configuration for the Windows Event Log receiver.