(AB#190107) Consolidate logging (#10724)

This change consolidates the information for configurable logging across the about topics and fixes AB#190107.
MicrosoftDocs · Dec 8, 2023 · 09b90c7 · 09b90c7
1 parent 23c6d9a
commit 09b90c7
Show file tree

Hide file tree

Showing 7 changed files with 425 additions and 169 deletions.
diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Eventlogs.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Eventlogs.md
@@ -1,7 +1,7 @@
 ---
 description: Windows PowerShell creates a Windows event log that is named Windows PowerShell to record Windows PowerShell events. You can view this log in Event Viewer or by using cmdlets that get events, such as the `Get-EventLog` cmdlet. By default, Windows PowerShell engine and provider events are recorded in the event log, but you can use the event log preference variables to customize the event log. For example, you can add events about Windows PowerShell commands.
 Locale: en-US
-ms.date: 03/01/2023
+ms.date: 12/08/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_eventlogs?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Eventlogs
@@ -14,29 +14,24 @@ This article describes how PowerShell logs events to the Windows Event log.
 
 ## Long description
 
-Windows PowerShell creates a Windows event log that is named "Windows
-PowerShell" to record Windows PowerShell events. You can view this log in
-Event Viewer or by using cmdlets that get events, such as the `Get-EventLog`
-cmdlet. By default, Windows PowerShell engine and provider events are recorded
-in the event log, but you can use the event log preference variables to
-customize the event log. For example, you can add events about Windows
-PowerShell commands.
+Windows PowerShell creates a Windows event log that's named "Windows
+PowerShell" to record Windows PowerShell events. You can view this log in Event
+Viewer or by using cmdlets that get events, such as the `Get-EventLog` cmdlet.
+By default, Windows PowerShell engine and provider events are recorded in the
+event log, but you can use the event log preference variables to customize the
+event log. For example, you can add events about Windows PowerShell commands.
 
 The Windows PowerShell event log records details of Windows PowerShell
 operations, such as starting and stopping the program engine and starting and
 stopping the Windows PowerShell providers. You can also log details about
 Windows PowerShell commands.
 
-The Windows PowerShell event log is in the Application and Services Logs
-group. The Windows PowerShell log is a classic event log that does not use the
-Windows Eventing technology. To view the log, use the cmdlets designed for
-classic event logs, such as `Get-EventLog`.
 
 ## Viewing the Windows PowerShell Event Log
 
 You can view the Windows PowerShell event log in Event Viewer or by using the
-`Get-EventLog` and `Get-WmiObject` cmdlets. To view the contents of the
-Windows PowerShell log, type:
+`Get-EventLog` and `Get-WmiObject` cmdlets. To view the contents of the Windows
+PowerShell log, type:
 
 ```powershell
 Get-EventLog -LogName "Windows PowerShell"
@@ -82,8 +77,7 @@ To find the Win32 event-related WMI classes, type:
 Get-WmiObject -List | where Name -Like "win32*event*"
 ```
 
-For more information, type "Get-Help Get-EventLog" and
-"Get-Help Get-WmiObject".
+For more information, see [Get-EventLog][05] and [Get-WmiObject][06].
 
 ## Selecting Events for the Windows PowerShell Event Log
 
@@ -97,27 +91,27 @@ and stopping events. The Health variables log error events.
 
 The following table lists the event log preference variables.
 
-|Variable                  |Description                                    |
-|--------------------------|-----------------------------------------------|
-|$LogEngineLifeCycleEvent  |Logs the start and stop of PowerShell          |
-|$LogEngineHealthEvent     |Logs PowerShell program errors                 |
-|$LogProviderLifeCycleEvent|Logs the start and stop of PowerShell providers|
-|$LogProviderHealthEvent   |Logs PowerShell provider errors                |
-|$LogCommandLifeCycleEvent |Logs the starting and completion of commands   |
-|$LogCommandHealthEvent    |Logs command errors                            |
+|           Variable           |                   Description                   |
+| ---------------------------- | ----------------------------------------------- |
+| `$LogEngineLifeCycleEvent`   | Logs the start and stop of PowerShell           |
+| `$LogEngineHealthEvent`      | Logs PowerShell program errors                  |
+| `$LogProviderLifeCycleEvent` | Logs the start and stop of PowerShell providers |
+| `$LogProviderHealthEvent`    | Logs PowerShell provider errors                 |
+| `$LogCommandLifeCycleEvent`  | Logs the starting and completion of commands    |
+| `$LogCommandHealthEvent`     | Logs command errors                             |
 
 (For information about Windows PowerShell providers, see
-[about_Providers](about_Providers.md).)
+[about_Providers][01].)
 
 By default, only the following event types are enabled:
 
-* $LogEngineLifeCycleEvent
-* $LogEngineHealthEvent
-* $LogProviderLifeCycleEvent
-* $LogProviderHealthEvent
+- `$LogEngineLifeCycleEvent`
+- `$LogEngineHealthEvent`
+- `$LogProviderLifeCycleEvent`
+- `$LogProviderHealthEvent`
 
 To enable an event type, set the preference variable for that event type to
-$true. For example, to enable command life-cycle events, type:
+`$true`. For example, to enable command life-cycle events, type:
 
 ```powershell
 $LogCommandLifeCycleEvent
@@ -130,62 +124,62 @@ $LogCommandLifeCycleEvent = $true
 ```
 
 To disable an event type, set the preference variable for that event type to
-$false. For example, to disable command life-cycle events, type:
+`$false`. For example, to disable command life-cycle events, type:
 
 ```powershell
 $LogProviderLifeCycleEvent = $false
 ```
 
-You can disable any event, except for the events that indicate that the
-Windows PowerShell engine and the core providers are started. These events are
-generated before the Windows PowerShell profiles are run and before the host
-program is ready to accept commands.
+You can disable any event, except for the events that indicate that the Windows
+PowerShell engine and the core providers started. These events generate before
+the Windows PowerShell profiles run and before the host program is ready to
+accept commands.
 
-The variable settings apply only for the current Windows PowerShell session.
-To apply them to all Windows PowerShell sessions, add them to your Windows
+The variable settings apply only for the current Windows PowerShell session. To
+apply them to all Windows PowerShell sessions, add them to your Windows
 PowerShell profile.
 
 ## Logging Module Events
 
 Beginning in Windows PowerShell 3.0, you can record execution events for the
-cmdlets and functions in Windows PowerShell modules and snap-ins by setting
-the LogPipelineExecutionDetails property of modules and snap-ins to TRUE. In
+cmdlets and functions in Windows PowerShell modules and snap-ins by setting the
+**LogPipelineExecutionDetails** property of modules and snap-ins to `$true`. In
 Windows PowerShell 2.0, this feature is available only for snap-ins.
 
-When the LogPipelineExecutionDetails property value is TRUE (`$true`), Windows
+When the **LogPipelineExecutionDetails** property value is `$true`, Windows
 PowerShell writes cmdlet and function execution events in the session to the
 Windows PowerShell log in Event Viewer. The setting is effective only in the
 current session.
 
-To enable logging of execution events of cmdlets and functions in a module,
-use the following command sequence.
+To enable logging of execution events of cmdlets and functions in a module, use
+the following command sequence.
 
 ```powershell
-Import-Module <ModuleName>
-$m = Get-Module <ModuleName>
+Import-Module Microsoft.PowerShell.Archive
+$m = Get-Module Microsoft.PowerShell.Archive
 $m.LogPipelineExecutionDetails = $true
 ```
 
 To enable logging of execution events of cmdlets in a snap-in, use the
 following command sequence.
 
 ```powershell
-$m = Get-PSSnapin <SnapInName> [-Registered]
+$m = Get-PSSnapin Microsoft.PowerShell.Core
 $m.LogPipelineExecutionDetails = $True
 ```
 
 To disable logging, use the same command sequence to set the property value to
-FALSE (`$false`).
+`$false`.
 
-You can also use the "Turn on Module Logging" Group Policy setting to enable
+You can also use the **Turn on Module Logging** Group Policy setting to enable
 and disable module and snap-in logging. The policy value includes a list of
 module and snap-in names. Wildcards are supported.
 
-When "Turn on Module Logging" is set for a module, the value of the
-LogPipelineExecutionDetails property of the module is TRUE in all sessions and
-it cannot be changed.
+When **Turn on Module Logging** is set for a module, the value of the
+**LogPipelineExecutionDetails** property of the module is `$true` in all
+sessions and it can't be changed.
 
-The Turn On Module Logging group policy setting is located in the following
+The "Turn On Module Logging" group policy setting is located in the following
 Group Policy paths:
 
 ```
@@ -205,31 +199,38 @@ policy, and both policies take preference over the value of the
 LogPipelineExecutionDetails property of modules and snap-ins.
 
 For more information about this Group Policy setting, see
-[about_Group_Policy_Settings](about_Group_Policy_Settings.md).
+[about_Group_Policy_Settings][03].
 
 ## Security and Auditing
 
 The Windows PowerShell event log is designed to indicate activity and to
 provide operational details for troubleshooting.
 
-However, like most Windows-based application event logs, the Windows
-PowerShell event log is not designed to be secure. It should not be used to
-audit security or to record confidential or proprietary information.
+However, like most Windows-based application event logs, the Windows PowerShell
+event log isn't designed to be secure. It shouldn't be used to audit security
+or to record confidential or proprietary information.
 
-Event logs are designed to be read and understood by users. Users can read
-from and write to the log. A malicious user could read an event log on a local
-or remote computer, record false data, and then prevent the logging of their
+Event logs are designed to be read and understood by users. Users can read from
+and write to the log. A malicious user could read an event log on a local or
+remote computer, record false data, and then prevent the logging of their
 activities.
 
 ## Notes
 
 Authors of module authors can add logging features to their modules. For more
-information, see
-[Writing a Windows PowerShell Module](/powershell/scripting/developer/module/writing-a-windows-powershell-module).
+information, see [Writing a Windows PowerShell Module][02].
 
 ## See also
 
-- [about_Group_Policy_Settings](about_Group_Policy_Settings.md)
-- [about_Preference_Variables](about_Preference_Variables.md)
-- [Get-EventLog](xref:Microsoft.PowerShell.Management.Get-EventLog)
-- [Get-WmiObject](xref:Microsoft.PowerShell.Management.Get-WmiObject)
+- [about_Group_Policy_Settings][03]
+- [about_Preference_Variables][04]
+- [Get-EventLog][05]
+- [Get-WmiObject][06]
+
+<!-- link references -->
+[01]: about_Providers.md
+[02]: /powershell/scripting/developer/module/writing-a-windows-powershell-module
+[03]: about_Group_Policy_Settings.md
+[04]: about_Preference_Variables.md
+[05]: xref:Microsoft.PowerShell.Management.Get-EventLog
+[06]: xref:Microsoft.PowerShell.Management.Get-WmiObject
diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Logging_Non-Windows.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Logging_Non-Windows.md
@@ -1,7 +1,7 @@
 ---
 description: PowerShell logs internal operations from the engine, providers, and cmdlets.
 Locale: en-US
-ms.date: 02/27/2023
+ms.date: 12/08/2023
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_logging_non-windows?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Logging Non-Windows
@@ -24,7 +24,44 @@ The location of PowerShell logs is dependent on the target platform.
   **syslog** server. For more information, see the `man` pages for your Linux
   distribution.
 - On macOS, Apple's unified logging system is used. For more information, see
-  [Apple's developer documentation on logging][03].
+  [Apple's developer documentation on logging][01].
+
+PowerShell supports configuring two categories of logging:
+
+- Module logging - Record the pipeline execution events for members of
+  specified modules. Module logging must be enabled for both the session and
+  specific modules. For more information about configuring this logging, see
+  [about_PowerShell_Config][02].
+
+  If module logging is enabled through configuration, you can enable and
+  disable logging for specific modules in a session by setting the value of the
+  **LogPipelineExecutionDetails** property of the module.
+
+  For example, to enable module logging for the **PSReadLine** module:
+
+  ```powershell
+  $psrl = Get-Module PSReadLine
+  $psrl.LogPipelineExecutionDetails = $true
+  Get-Module PSReadline | Select-Object Name, LogPipelineExecutionDetails
+  ```
+
+  ```Output
+  Name       LogPipelineExecutionDetails
+  ----       ---------------------------
+  PSReadLine                        True
+  ```
+
+- Script block logging - Record the processing of commands, script blocks,
+  functions, and scripts whether invoked interactively, or through automation.
+
+  When you enable Script Block Logging, PowerShell records the content of all
+  script blocks that it processes. Once enabled, any new PowerShell session
+  logs this information.
+
+  > [!NOTE]
+  > It's recommended to enable Protected Event Logging, when using Script Block
+  > Logging for anything other than diagnostics purposes. For more information,
+  > see [about_PowerShell_Config][03].
 
 ## Configuring logging on Linux or macOS
 
@@ -43,18 +80,18 @@ The following code is an example configuration:
 
 ```json
 {
-  "ScriptBlockLogging": {
-    "EnableScriptBlockInvocationLogging": true,
-    "EnableScriptBlockLogging": true
-  },
-  "ModuleLogging": {
-    "EnableModuleLogging": false,
-    "ModuleNames": [
-      "PSReadLine",
-      "PowerShellGet"
-    ]
-  },
-  "LogLevel": "verbose"
+    "ModuleLogging": {
+        "EnableModuleLogging": false,
+        "ModuleNames": [
+            "PSReadLine",
+            "PowerShellGet"
+        ]
+    },
+    "ScriptBlockLogging": {
+        "EnableScriptBlockInvocationLogging": true,
+        "EnableScriptBlockLogging": true
+    },
+    "LogLevel": "verbose"
 }
 ```
 
@@ -84,6 +121,10 @@ value.
   - Description: Keywords provide the ability to limit logging to specific
     components within PowerShell. By default, all keywords are enabled and
     change this value is only useful for specialized troubleshooting.
+- **PowerShellPolicies**
+  - Description: The **PowerShellPolicies** setting contains the
+    **ModuleLogging**, **ProtectedEventLogging**, and **ScriptBlockLogging**
+    options. For more information, see [Common configuration settings][04].
 
 ## Viewing PowerShell log data in journald on Linux
 
@@ -328,22 +369,25 @@ For more information, run `log show --help` to view the help for the `log show`
 command.
 
 You may also want to consider saving the logs to a more secure location such as
-[Security Information and Event Management (SIEM)][04] aggregator. Using
+[Security Information and Event Management (SIEM)][06] aggregator. Using
 Microsoft Defender for Cloud Apps, you can set up SIEM in Azure. For more
-information, see [Generic SIEM integration][01].
+information, see [Generic SIEM integration][07].
 
 ## See also
 
 - For Linux **syslog** and **rsyslog.conf** information, refer to the Linux
   computer's local `man` pages
 - For macOS **logging** information, see
-  [Apple's developer documentation on logging][03]
-- For Windows, see [about_Logging_Windows][02]
-- [Generic SIEM integration][01]
+  [Apple's developer documentation on logging][01]
+- For Windows, see [about_Logging_Windows][08]
+- [Generic SIEM integration][07]
 
 <!-- link references -->
-[01]: /defender-cloud-apps/siem
-[02]: about_Logging_Windows.md
-[03]: https://developer.apple.com/documentation/os/logging
-[04]: https://wikipedia.org/wiki/Security_information_and_event_management
+[01]: https://developer.apple.com/documentation/os/logging
+[02]: about_PowerShell_Config.md#modulelogging
+[03]: about_PowerShell_Config.md#protectedeventlogging
+[04]: about_PowerShell_Config.md#common-configuration-settings
 [05]: https://support.apple.com/guide/console/log-messages-cnsl1012/mac
+[06]: https://wikipedia.org/wiki/Security_information_and_event_management
+[07]: /defender-cloud-apps/siem
+[08]: about_Logging_Windows.md