[7.17](backport #34931) winlogbeat/docs: improve event_logs.name docs (…

…#34948)

* winlogbeat/docs: improve event_logs.name docs (#34931)

This introduces the concept of event log names earlier in the documentation and
provides the preferred PowerShell cmdlet first, before showing the fallback
cmdlet if the preferred option is not available.

Links to the Microsoft documentation for the cmdlets is also added.

(cherry picked from commit bd93c11)

* fix changelog entry

---------

Co-authored-by: Dan Kortschak <90160302+efd6@users.noreply.github.com>

CHANGELOG.next.asciidoc

@@ -59,6 +59,7 @@ https://github.com/elastic/beats/compare/v7.0.0-alpha2...master[Check the HEAD d
 - Fix handling of event data with keys containing dots. {issue}34345[34345] {pull}34549[34549]
 - Gracefully handle channel not found errors. {issue}30201[30201] {pull}34605[34605]
 - Clarify query term limits warning and remove link to missing Microsoft doc page. {pull}34715[34715]
+- Improve documentation for event_logs.name configuration. {pull}34931[34931]
 
 *Functionbeat*
 

winlogbeat/docs/winlogbeat-options.asciidoc

@@ -112,29 +112,12 @@ reading additional event log records.
 ==== `event_logs.name`
 
 The name of the event log to monitor. Each dictionary under `event_logs` must
-have a `name` field, except for those which use a custom XML query. You can
-get a list of available event logs by running `Get-EventLog *` in PowerShell.
-Here is a sample of the output from the command:
-
-[source,sh]
---------------------------------------------------------------------------------
-PS C:\Users\vagrant> Get-EventLog *
-
-  Max(K) Retain OverflowAction        Entries Log
-  ------ ------ --------------        ------- ---
-  20,480      0 OverwriteAsNeeded          75 Application
-  20,480      0 OverwriteAsNeeded           0 HardwareEvents
-     512      7 OverwriteOlder              0 Internet Explorer
-  20,480      0 OverwriteAsNeeded           0 Key Management Service
-  20,480      0 OverwriteAsNeeded       1,609 Security
-  20,480      0 OverwriteAsNeeded       1,184 System
-  15,360      0 OverwriteAsNeeded         464 Windows PowerShell
---------------------------------------------------------------------------------
-
-Channel names can also be specified if running on Windows Vista or newer. A
-channel is a named stream of events that transports events from an event source
-to an event log. Most channels are tied to specific event publishers. Here is an
-example showing how to list all channels using PowerShell.
+have a `name` field, except for those which use a custom XML query.
+A channel is a named stream of events that transports events from an event
+source to an event log. Most channels are tied to specific event publishers.
+You can get a list of available event logs by using the PowerShell
+https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.diagnostics/get-winevent[`Get-WinEvent`] cmdlet
+on Windows Vista or newer. Here is a sample of the output from the command:
 
 [source,sh]
 --------------------------------------------------------------------------------
@@ -154,6 +137,24 @@ LogName : Microsoft-Windows-Windows Firewall With Advanced Security/Firewall
 ...
 --------------------------------------------------------------------------------
 
+If `Get-WinEvent` is not available, the https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/get-eventlog[`Get-EventLog`] cmdlet can be used in its
+place.
+
+[source,sh]
+--------------------------------------------------------------------------------
+PS C:\Users\vagrant> Get-EventLog *
+
+  Max(K) Retain OverflowAction        Entries Log
+  ------ ------ --------------        ------- ---
+  20,480      0 OverwriteAsNeeded          75 Application
+  20,480      0 OverwriteAsNeeded           0 HardwareEvents
+     512      7 OverwriteOlder              0 Internet Explorer
+  20,480      0 OverwriteAsNeeded           0 Key Management Service
+  20,480      0 OverwriteAsNeeded       1,609 Security
+  20,480      0 OverwriteAsNeeded       1,184 System
+  15,360      0 OverwriteAsNeeded         464 Windows PowerShell
+--------------------------------------------------------------------------------
+
 You must specify the full name of the channel in the configuration file.
 
 [source,yaml]