[pkg/stanza/operator/input/windows] [receiver/windowseventlogreceiver] Add include providers

[OverOrion]

Description

Adds the ability to filter for specific providers, the opposite of exclude_providers.

Usage

  windowseventlog/include:
    channel: "application"
    raw: true
    include_providers: ["foo", "asd"]

I tested it manually using the following:

eventcreate /t ERROR /id 100 /l application /d "Create event in application log"  /so foo

2025-03-11T08:27:47.699Z        info    [email protected]/service.go:281   Everything is ready. Begin running and processing data.
2025-03-11T08:27:52.799Z        info    Logs    {"otelcol.component.id": "debug", "otelcol.component.kind": "Exporter", "otelcol.signal": "logs", "resource logs": 1, "log records": 1}
2025-03-11T08:27:52.800Z        info    ResourceLog #0
Resource SchemaURL:
ScopeLogs #0
ScopeLogs SchemaURL:
InstrumentationScope
LogRecord #0
ObservedTimestamp: 2025-03-11 08:27:52.7010582 +0000 UTC
Timestamp: 2025-03-11 08:27:52.3766645 +0000 UTC
SeverityText: ERROR
SeverityNumber: Error(17)
Body: Str(<Event xmlns='http://schemas.microsoft.com/win/2004/08/events/event'><System><Provider Name='foo'/><EventID Qualifiers='0'>100</EventID><Version>0</Version><Level>2</Level><Task>0</Task><Opcode>0</Opcode><Keywords>0x80000000000000</Keywords><TimeCreated SystemTime='2025-03-11T08:27:52.3766645Z'/><EventRecordID>18970</EventRecordID><Correlation/><Execution ProcessID='0' ThreadID='0'/><Channel>Application</Channel><Computer>WIN-QPSC869NP87</Computer><Security UserID='S-1-5-21-133525999-567665136-2406734344-1000'/></System><EventData><Data>Create event in application log</Data></EventData><RenderingInfo Culture='en-US'><Message>Create event in application log</Message><Level>Error</Level><Task></Task><Opcode>Info</Opcode><Channel></Channel><Provider></Provider><Keywords><Keyword>Classic</Keyword></Keywords></RenderingInfo></Event>)
Trace ID:
Span ID:
Flags: 0
        {"otelcol.component.id": "debug", "otelcol.component.kind": "Exporter", "otelcol.signal": "logs"}

[djaglowski]

Why is this necessary? Isn't a provider included unless it is excluded explicitly? Are you able to write a test which fails without this change?

[OverOrion]

Hey @djaglowski
Thanks for the quick look!

I believe it's necessary as I do not think there's a way to express this: Application channel logs only from a specific provider (providerFoo).

Writing it using exclude_providers is not possible as providers could change and the new provider would be accepted as well (would not be present in the exclude_providers list).

[djaglowski]

Thanks for clarifying. Given your explanation I think this makes sense but I think documentation needs to be super clear about how include and exclude work together.

[OverOrion]

Sure thing @djaglowski, that's a valid concern!

Should I also add a validation that checks whether a given provider is present both in the include/exclude list? I think that should result in a hard error.

This is what I currently have in my mind regarding docs:
By default no filter is applied for providers, meaning that every providers' events are forwarded.
If you want to include only specific providers, then include_providers parameter should be used.
If you want to exclude only specific providers, then exclude_providers parameter should be used.
If include_providers is specified, then only providers present in the include_providers list are forwarded.
For example:

  windowseventlog/include_and_exclude:
    channel: "application"
    include_providers: ["foo"]
    exclude_providers: ["bar"]

The previous example snippet will only forward events if the event's provider is foo, meaning that events from a provider named foobar are excluded implicitly.

[pjanotti]

Thanks for the PR @OverOrion! It makes sense to have the include_providers, however, we should try to leverage the Win32 API to implement it since one of the possible reasons to use such feature is to reduce the amount of work done by the receiver.