Skip to content

docs: inputs: winevtlog: add render_event_as_text params and fix table formatting #2504

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eschabell merged 1 commit into from
Mar 20, 2026
+63 −21
Merged

docs: inputs: winevtlog: add render_event_as_text params and fix table formatting #2504

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 63 additions & 21 deletions pipeline/inputs/windows-event-log-winevtlog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,24 @@ The plugin supports the following configuration parameters:

| Key | Description | Default |
|:--------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------|
| `Channels` | A comma-separated list of channels to read from. | _none_ |
| `Interval_Sec` | Optional. Set the polling interval for each channel. | `1` |
| `Interval_NSec` | Optional. Set the polling interval for each channel. (nanoseconds) | `0 ` |
| `Read_Existing_Events` | Optional. Whether to read existing events from head or tailing events at last on subscribing. | `False` |
| `DB` | Optional. Set the path to save the read offsets. | _none_ |
| `String_Inserts` | Optional. Whether to include string inserts in output records. | `True` |
| `Render_Event_As_XML` | Optional. Whether to render the system part of an event as an XML string or not. | `False` |
| `Ignore_Missing_Channels` | Optional. Whether to ignore event channels not present in the event log, and continue running with subscribed channels. | `False` |
| `Use_ANSI` | Optional. Use ANSI encoding on `eventlog` messages. If you have issues receiving blank strings with old Windows versions (Server 2012 R2), setting this to `True` might solve the problem. | `False` |
| `Event_Query` | Specify XML query for filtering events. | `*` |
| `Read_Limit_Per_Cycle` | Specify read limit per cycle. | `512KiB` |
| Threaded | Indicates whether to run this input in its own [thread](../../administration/multithreading.md#inputs). | `false` |
| `Remote.Server` | Specify server name of remote access for Windows EventLog. | _none_ |
| `Remote.Domain` | Specify domain name of remote access for Windows EventLog. | _none_ |
| `Remote.Username` | Specify user name of remote access for Windows EventLog. | _none_ |
| `Remote.Password` | Specify password of remote access for Windows EventLog. | _none_ |
| `channels` | A comma-separated list of channels to read from. | _none_ |
| `db` | Optional. Set the path to save the read offsets. | _none_ |
| `event_query` | Specify XML query for filtering events. | `*` |
| `ignore_missing_channels` | Optional. Whether to ignore event channels not present in the event log, and continue running with subscribed channels. | `false` |
| `interval_nsec` | Optional. Set the polling interval for each channel. (nanoseconds) | `0` |
| `interval_sec` | Optional. Set the polling interval for each channel. | `1` |
| `read_existing_events` | Optional. Whether to read existing events from head or tailing events at last on subscribing. | `false` |
| `read_limit_per_cycle` | Specify read limit per cycle. | `512KiB` |
| `remote.domain` | Specify domain name of remote access for Windows EventLog. | _none_ |
| `remote.password` | Specify password of remote access for Windows EventLog. | _none_ |
| `remote.server` | Specify server name of remote access for Windows EventLog. | _none_ |
| `remote.username` | Specify user name of remote access for Windows EventLog. | _none_ |
| `render_event_as_text` | Optional. Render the Windows EventLog event as newline-separated `key=value` text. Mutually exclusive with `render_event_as_xml`. | `false` |
| `render_event_as_xml` | Optional. Render the Windows EventLog event as XML, including the System and Message fields. Mutually exclusive with `render_event_as_text`. | `false` |
| `render_event_text_key` | Optional. Record key name used to store the rendered text when `render_event_as_text` is enabled. | `log` |
| `string_inserts` | Optional. Whether to include string inserts in output records. | `true` |
| `threaded` | Indicates whether to run this input in its own [thread](../../administration/multithreading.md#inputs). | `false` |
| `use_ansi` | Optional. Use ANSI encoding on `eventlog` messages. If you have issues receiving blank strings with old Windows versions (Server 2012 R2), setting this to `true` might solve the problem. | `false` |

If `db` isn't set, the plugin will tail channels on each startup.

Expand Down Expand Up @@ -69,23 +71,63 @@ pipeline:

Some Windows Event Log channels, like `Security`, require administrative privilege for reading. In this case, you must run Fluent Bit as an administrator.

The default value of `Read_Limit_Per_Cycle` is `512KiB`.
The default value of `read_limit_per_cycle` is `512KiB`.

512 KiB(= 0x7ffff = 512 * 1024 * 1024) isn't equal to 512 KB (= 512 * 1000 * 1000). To increase events per second on this plugin, specify larger value than 512 KiB.

#### Query languages for `Event_Query` parameter
#### Query languages for `event_query` parameter

The `Event_Query` parameter can be used to specify the XML query for filtering Windows EventLog during collection.
The `event_query` parameter can be used to specify the XML query for filtering Windows EventLog during collection.
The supported query types are [`XPath`](https://developer.mozilla.org/en-US/docs/Web/XML/XPath) and XML Query.
For further details, refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/windows/win32/wes/consuming-events).

### Render events as text

When `render_event_as_text` is set to `true`, each event is rendered as a newline-separated `key=value` string and stored under the key specified by `render_event_text_key`. This mode is mutually exclusive with `render_event_as_xml`—enabling both causes the plugin to exit with an error.

{% tabs %}
{% tab title="fluent-bit.yaml" %}

```yaml
pipeline:
inputs:
- name: winevtlog
channels: Setup,Windows PowerShell
db: winevtlog.sqlite
render_event_as_text: true
render_event_text_key: log

outputs:
- name: stdout
match: '*'
```

{% endtab %}
{% tab title="fluent-bit.conf" %}

```text
[INPUT]
Name winevtlog
Channels Setup,Windows PowerShell
DB winevtlog.sqlite
Render_Event_As_Text true
Render_Event_Text_Key log

[OUTPUT]
Name stdout
Match *
```

{% endtab %}
{% endtabs %}

### Command line

If you want to do a test, you can run this plugin from the command line:

```shell
fluent-bit -i winevtlog -p 'channels=Setup' -p 'Read_Existing_Events=true' -o stdout
fluent-bit -i winevtlog -p 'channels=Setup' -p 'read_existing_events=true' -o stdout
```

The `winevtlog` plugin will tail channels on each startup.
If you want to confirm whether this plugin is working or not, specify the `-p 'Read_Existing_Events=true'` parameter.
If you want to confirm whether this plugin is working or not, specify the `-p 'read_existing_events=true'` parameter.
Loading