diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md new file mode 100644 index 000000000000..f22df57b0193 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -0,0 +1,203 @@ +--- +ms.date: 2017-12-04 +schema: 2.0.0 +locale: en-us +keywords: powershell +title: about_Logging +--- + +# About Logging + +## Short Description + +PowerShell logs internal operations from the engine, providers, and +cmdlets. + + +## Long Description + +PowerShell logs details of PowerShell operations, such as starting +and stopping the engine and starting and stopping providers. It will +also log details about PowerShell commands. + +The location of PowerShell logs is dependent on the target platform. +On Windows, PowerShell logs to the event log, on Linux, PowerShell logs +to syslog, and on MacOS, the os_log logging system is used. + +## Viewing the PowerShell event log on Windows + +PowerShell logs can be viewed using the Event Viewer. The event log is +located in the Application and Services Logs group and is named PowerShellCore. +The associated ETW provider guid is `{f90714a8-5509-434a-bf6d-b1624c8a19a2}` + +### Registering the PowerShell event provider on Windows + +Unlike Linux or MacOS, Windows requires the event provider to be registered +before logged events can appear in the event log. For PowerShell, this is +accomplished by running the `RegisterManifest.ps1` from an elevated +PowerShell prompt. + +The script is located in the the $PSHOME directory and should be run from +that location. + +### Unregistering the PowerShell event provider on Windows + +Registering an event provider places a lock in the binary containing the data +needed to decode events. To update this binary, the provider must first be +unregistered to release this lock. + +To unregister the PowerShell provider, run the `RegisterManifest.ps1` from an +elevated PowerShell prompt and specify the `-Unregister` switch. Once the +upgrade of PowerShell has completed, run `RegisterManifest.ps1` a second time +to register the updated ETW provider. + +## Viewing PowerShell log output on Linux + +PowerShell logs to syslog on Linux and any of the tools commonly used to view +syslog contents may be used. + +The format of the log entries uses the following template: + +``` +TIMESTAMP MACHINENAME powershell[PID]: (COMMITID:TID:CID) + [EVENTID:TASK.OPCODE.LEVEL] MESSAGE +``` + +|Field |Description | +|-------------|--------------------------------------------------------| +|`TIMESTAMP` |A date/time when the log entry was produced. | +|`MACHINENAME`|The name of the system where the log was produced. | +|`PID` |The process id of the process that wrote the log entry. | +|`COMMITID` |The git commit id or tag used to produce the build. | +|`TID` |The thread id of the thread that wrote the log entry. | +|`CID` |The hex channel identifier of the log entry. | +| |10 = Operational, 11 = Analytic | +|`EVENTID` |The event identifier of the log entry. | +|`TASK` |The task identifier for the event entry | +|`OPCODE` |The opcode for the event entry | +|`LEVEL` |The log level for the event entry | +|`MESSAGE` |The message associated with the event entry | + +* NOTE: EVENTID, TASK, OPCODE, and LEVEL are the same values as used when +logging to the windows event log. + +### Filtering PowerShell log entries using rsyslog + +By default, PowerShell log entries are written to the default location/file +for syslog. However, it is possible to redirect the entries to a custom +file. + +* Create a conf for PowerShell log configuration and provide a number that +is less than 50 (for `50-default.conf`), such as `40-powershell.conf`. The +file should be placed under `/etc/rsyslog.d`. + +* Add the following entry to the file +``` +:syslogtag, contains, "powershell[" /var/log/powershell.log +& stop +``` +* Ensure `/etc/rsyslog.conf` includes the new file. Often, it will have +a generic include statement that looks like following: + +`$IncludeCnofig /etc/rsyslog.d/*.conf` + +If it does not, you will need to add an include statement manually. + +* Ensure attributes and permissions are set appropriately + +``` +-rw-r--r-- 1 root root 67 Nov 28 12:51 40-powershell.conf +``` +- Set ownership to root +``` +chown root:root /etc/rsyslog.d/40-powershell.conf +``` +- Set access permissions - root has read/write, users have read. +``` +chmod 644 /etc/rsyslog.d/40-powershell.conf +``` + +## Viewing PowerShell log output on MacOS + +The easiest method for viewing PowerShell log output on MacOS is using the +Console application. + +* Search for the Console application and launch it +* Select the Machine name under Devices +* In the Search field, entry 'pwsh'; the PowerShell main binary. +* Change search filter from 'Any' to 'Process' +* Peform the operations +* Optionally save the search for future use. + +To filter on a specific process instance of PowerShell in the Console, the +variable $pid contains the process id. +* Enter the pid (Process Id) in the Search field. +* Change search filter PID +* Perform the operations + +### Viewing PowerShell log output from a command-line + +The `log` command can be used to view PowerShell log entries from the +command-line. + +``` +sudo log stream --predicate 'process == "pwsh"' --info +``` + +## Configuring Logging on non-Windows systems + +On Windows, logging is configured by creating ETW trace listeners or by using +the Event Viewer to enable Analytic logging. On Linux and MacOS, logging is +configured using the file `PowerShellProperties.json`. The rest of this section +will discuss configuring PowerShell logging on non-Windows system. + +By default, PowerShell enables informational logging to the operational +channel. What this means is any log output produced by PowerShell that is +marked as operational and has a log (trace) level greater then informational +will be logged. Occasionally, diagnoses may require additional log output, +such as verbose log output or enabling analytic log output. + +The file `PowerShellProperties.json` is a JSON formatted file residing in the +PowerShell $PSHOME directory. Each installation of PowerShell uses it's own +copy of this file. For normal operation, this file is left unchanged but it +can be useful for diagnosis or for distinguishing between multiple PowerShell +versions on the same system or even multiple copies of the same version +(See LogIdentity in the table below). + +The properties for configuring PowerShell logging are listed in the following +table. +Values marked with an asterick, such as `Operational*`, indicate the default +value when no value is provided in the file. + +|Property |Values |Description | +|-----------|--------------|---------------------------------------------| +|LogIdentity|(string name) |The name to use when logging. By default, | +| |powershell* |powershell is the identity. This value can be| +| | |used to distinguish between two instances of | +| | |a PowerShell installation, such as a release | +| | |and beta version. This value is also used to | +| | |redirect log output to a separate file on | +| | |Linux. See the discussion of rsyslog above. | +|LogChannels|Operational* |The channels to enable. Seperate the values | +| |Analytic |with a comma when specifying more than one. | +|LogLevel |Always |Specify a single value. The value enables | +| |Critical |itself as well as all values above it in the | +| |Error |list to the left. | +| |Warning | | +| |Informational*| | +| |Verbose | | +| |Debug | | +|LogKeywords|Runspace |Keywords provide the ability to limit logging| +| |Pipeline |to specific components within PowerShell. By | +| |Protocol |default, all keywords are enabled and change | +| |Transport |this value is generaly only useful for very | +| |Host |specialized trouble shooting. | +| |Cmdlets | | +| |Serializer | | +| |Session | | +| |ManagedPlugin | | + +## SEE ALSO +- syslog and rsyslog.conf man pages. +- os_log developer documentation +- Event Viewer