From 1269e42a8a29e685059dbc65a1374db575e4301d Mon Sep 17 00:00:00 2001 From: Dan Travison Date: Mon, 4 Dec 2017 18:06:15 -0800 Subject: [PATCH 1/5] First draft of PowerShell 6 logging --- .../About/about_Logging.md | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 reference/6/Microsoft.PowerShell.Core/About/about_Logging.md 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..176432fda363 --- /dev/null +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -0,0 +1,127 @@ +--- +ms.date: 2017-12-04 +schema: 2.0.0 +locale: en-us +keywords: powershell +title: about_Logging +--- + +# About Logging + +## Short Description + +PowerShell logs details of PowerShell operations, such as starting +and stopping the program engine and starting and stopping PowerShell +providers. it will also log details about PowerShell commands. + +## Long Description + +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 install 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 the 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 that was 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 +``` + +## 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, teh variable $pid contains the process id. +* Entry 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 +``` \ No newline at end of file From b2396e8c0b3142617fda4920117582e1eb1f2823 Mon Sep 17 00:00:00 2001 From: Dan Travison Date: Mon, 4 Dec 2017 18:17:40 -0800 Subject: [PATCH 2/5] Fix style guideline issues. --- reference/6/Microsoft.PowerShell.Core/About/about_Logging.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md index 176432fda363..d8ff19901716 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -110,13 +110,13 @@ The easiest method for viewing PowerShell log output on MacOS is using the Conso * 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. +* Peform the operations * Optionally save the search for future use. To filter on a specific process instance of PowerShell in the Console, teh variable $pid contains the process id. * Entry the pid (Process Id) in the Search field. * Change search filter PID -* Perform the operations. +* Perform the operations ### Viewing PowerShell log output from a command-line From 8783276143df7788ddf60ccc03414492355578c1 Mon Sep 17 00:00:00 2001 From: Dan Travison Date: Tue, 5 Dec 2017 11:28:47 -0800 Subject: [PATCH 3/5] Document logging settings in PowerShellProperties.json --- .../About/about_Logging.md | 21 +++++++++++++++++-- 1 file changed, 19 insertions(+), 2 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md index d8ff19901716..fd2169827665 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -114,7 +114,7 @@ The easiest method for viewing PowerShell log output on MacOS is using the Conso * Optionally save the search for future use. To filter on a specific process instance of PowerShell in the Console, teh variable $pid contains the process id. -* Entry the pid (Process Id) in the Search field. +* Enter the pid (Process Id) in the Search field. * Change search filter PID * Perform the operations @@ -124,4 +124,21 @@ The `log` command can be used to view PowerShell log entries from the command-li ``` sudo log stream --predicate 'process == "pwsh"' --info -``` \ No newline at end of file +``` + +## 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 isc onfigured 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 installation 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)
powershell* | The name to use when logging. By default, powershell is the identity. This 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 logging output to a sepearate file on Linux. See the discussion of rsyslog above. | +| LogChannels | Operational*
Analytic | The channels to enable.
Seperate the values with a comma when specifying more than one. +| LogLevel | Always
Critical
Error
Warning
Informational*
Verbose
Debug|Specify a single value. The value enables itself as well as all values above it in the list to the left | +| LogKeywords | Runspace
Pipeline
Protocol
Transport
Host
Cmdlets
Serializer
Session
ManagedPlugin | Keywords provide the ability to limit logging to specific components within PowerShell. By default, all keywords are enabled and change this value is generaly only useful for very specialized trouble shooting. | From 2cdf971865475836d109af22cd409637bea2d3ef Mon Sep 17 00:00:00 2001 From: dantraMSFT Date: Sat, 16 Dec 2017 16:37:04 -0800 Subject: [PATCH 4/5] Address PR Feedback Limit lines to 80 columns, when possible Insert
in selected locations to improve readability of rendered markdown. --- .../About/about_Logging.md | 97 +++++++++++++------ 1 file changed, 67 insertions(+), 30 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md index fd2169827665..4e17e143086d 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -10,12 +10,16 @@ title: about_Logging ## Short Description -PowerShell logs details of PowerShell operations, such as starting -and stopping the program engine and starting and stopping PowerShell -providers. it will also log details about PowerShell commands. +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. @@ -24,7 +28,7 @@ to syslog, and on MacOS, the os_log logging system is used. 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}' +The associated ETW provider guid is `{f90714a8-5509-434a-bf6d-b1624c8a19a2}` ### Registering the PowerShell event provider on Windows @@ -33,7 +37,8 @@ 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 install directory and should be run from that location. +The script is located in the the $PSHOME directory and should be run from +that location. ### Unregistering the PowerShell event provider on Windows @@ -48,7 +53,7 @@ to register the updated ETW provider. ## Viewing PowerShell log output on Linux -PowerShell logs the syslog on Linux and any of the tools commonly used to view +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: @@ -57,8 +62,8 @@ The format of the log entries uses the following template: TIMESTAMP MACHINENAME powershell[PID]: (COMMITID:TID:CID) [EVENTID:TASK.OPCODE.LEVEL] MESSAGE ``` -| Field | Description -|-------------|---| +| 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. @@ -66,16 +71,17 @@ TIMESTAMP MACHINENAME powershell[PID]: (COMMITID:TID:CID) [EVENTID:TASK.OPCODE.L | `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 +| `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 +* 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. @@ -101,10 +107,19 @@ If it does not, you will need to add an include statement manually. ``` -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. +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 @@ -113,32 +128,54 @@ The easiest method for viewing PowerShell log output on MacOS is using the Conso * Peform the operations * Optionally save the search for future use. -To filter on a specific process instance of PowerShell in the Console, teh variable $pid contains the process id. +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. +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 isc onfigured 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 installation 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)
powershell* | The name to use when logging. By default, powershell is the identity. This 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 logging output to a sepearate file on Linux. See the discussion of rsyslog above. | -| LogChannels | Operational*
Analytic | The channels to enable.
Seperate the values with a comma when specifying more than one. -| LogLevel | Always
Critical
Error
Warning
Informational*
Verbose
Debug|Specify a single value. The value enables itself as well as all values above it in the list to the left | -| LogKeywords | Runspace
Pipeline
Protocol
Transport
Host
Cmdlets
Serializer
Session
ManagedPlugin | Keywords provide the ability to limit logging to specific components within PowerShell. By default, all keywords are enabled and change this value is generaly only useful for very specialized trouble shooting. | +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)
powershell* | The name to use when logging.
By default, 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 logging output to a separate file on Linux.
See the discussion of rsyslog above. | +| LogChannels | Operational*
Analytic | The channels to enable.
Seperate the values with a comma when specifying more than one. +| LogLevel | Always
Critical
Error
Warning
Informational*
Verbose
Debug|Specify a single value. The value enables itself as well as all values above it in the list to the left | +| LogKeywords | Runspace
Pipeline
Protocol
Transport
Host
Cmdlets
Serializer
Session
ManagedPlugin | Keywords provide the ability to limit logging to specific components within PowerShell.
By default, all keywords are enabled and change this value is generaly only useful for very specialized trouble shooting. | + +## SEE ALSO +- syslog and rsyslog.conf man pages. +- os_log developer documentation +- Event Viewer \ No newline at end of file From dce3112a0a951bf53208c7988f3a27ecbf5bf9d0 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Wed, 3 Jan 2018 12:30:47 -0800 Subject: [PATCH 5/5] Reformatted tables Reformatted tables to work with new processing of About_* topics --- .../About/about_Logging.md | 66 ++++++++++++------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md index 4e17e143086d..f22df57b0193 100644 --- a/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md +++ b/reference/6/Microsoft.PowerShell.Core/About/about_Logging.md @@ -59,23 +59,24 @@ 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 +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 that was 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 -| +|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. @@ -168,14 +169,35 @@ 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)
powershell* | The name to use when logging.
By default, 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 logging output to a separate file on Linux.
See the discussion of rsyslog above. | -| LogChannels | Operational*
Analytic | The channels to enable.
Seperate the values with a comma when specifying more than one. -| LogLevel | Always
Critical
Error
Warning
Informational*
Verbose
Debug|Specify a single value. The value enables itself as well as all values above it in the list to the left | -| LogKeywords | Runspace
Pipeline
Protocol
Transport
Host
Cmdlets
Serializer
Session
ManagedPlugin | Keywords provide the ability to limit logging to specific components within PowerShell.
By default, all keywords are enabled and change this value is generaly only useful for very specialized trouble shooting. | +|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 \ No newline at end of file +- Event Viewer