Merge pull request #4794 from KoenZomers/AddedInMemoryLogging

Added in memory logging option

Author: KoenZomers

CHANGELOG.md

@@ -60,6 +60,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/).
 - Added `Set-PnPSiteDocumentIdPrefix` which allows changing of the document id prefix on a site collection [#4765](https://github.com/pnp/powershell/pull/4765)
 - Added `Get-PnPMicrosoft365Roadmap` which allows retrieval of the Microsoft 365 Roadmap items [#4764](https://github.com/pnp/powershell/pull/4764)
 - Added `-Name` parameter to `Add-PnPApplicationCustomizer` cmdlet to allow for specifying the name of the application customizer [#4767](https://github.com/pnp/powershell/pull/4767)
+- Added `Get-PnPTraceLog` cmdlet which allows reading from the detailed in memory logs of the PnP PowerShell cmdlet execution [#4794](https://github.com/pnp/powershell/pull/4794)
 
 ### Changed
 

documentation/Clear-PnPTraceLog.md

@@ -0,0 +1,51 @@
+---
+Module Name: PnP.PowerShell
+title: Clear-PnPTraceLog
+schema: 2.0.0
+applicable: SharePoint Online
+external help file: PnP.PowerShell.dll-Help.xml
+online version: https://pnp.github.io/powershell/cmdlets/Clear-PnPTraceLog.html
+---
+ 
+# Clear-PnPTraceLog
+
+## SYNOPSIS
+Clears the log stream in memory
+
+## SYNTAX
+
+```powershell
+Clear-PnPTraceLog [-Verbose]
+```
+
+## DESCRIPTION
+This clears the in memory stored log stream which was started with the [Start-PnPTraceLog -WriteToLogstream](Start-PnPTraceLog.md) cmdlet. It will not clear the log file if one was specified.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Clear-PnPTraceLog
+```
+
+This clears the in memory stored log stream
+
+## PARAMETERS
+
+### -Verbose
+When provided, additional debug statements will be shown while executing the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Get-PnPTraceLog.md

@@ -0,0 +1,111 @@
+---
+Module Name: PnP.PowerShell
+title: Get-PnPTraceLog
+schema: 2.0.0
+applicable: SharePoint Online
+external help file: PnP.PowerShell.dll-Help.xml
+online version: https://pnp.github.io/powershell/cmdlets/Get-PnPTraceLog.html
+---
+ 
+# Get-PnPTraceLog
+
+## SYNOPSIS
+Returns logged messages during the execution of PnP PowerShell cmdlets
+
+## SYNTAX
+
+### Log from file
+
+```powershell
+Get-PnPTraceLog -Path <string> [-Verbose]
+```
+### Log from log stream
+
+```powershell
+Get-PnPTraceLog [-Verbose]
+```
+
+## DESCRIPTION
+This cmdlet returns the logged messages during the execution of PnP PowerShell cmdlets. It can return the messages from an in memory log stream or from a file. Note that you cannot read from a log file if it is currently in use to write to. In this case, you would first have to stop logging to it using [Stop-PnPTraceLog](Stop-PnPTraceLog.md) and then read the log file. The in memory log stream is always available.
+
+You can use [Start-PnPTraceLog](Start-PnPTraceLog.md) to start logging to a file and/or to an in memory stream.
+
+## EXAMPLES
+
+### EXAMPLE 1
+```powershell
+Get-PnPTraceLog
+```
+
+This returns all items in the in memory stored log stream
+
+### EXAMPLE 2
+```powershell
+Get-PnPTraceLog -Path "C:\temp\log.txt"
+```
+
+This returns all items from the log file stored at the provided location. Note that you cannot read from a log file if it is currently in use to write to. In this case, you would first have to stop logging to it using [Stop-PnPTraceLog](Stop-PnPTraceLog.md) and then read the log file.
+
+### EXAMPLE 3
+```powershell
+Get-PnPTraceLog | Where-Object { $_.Level -eq "Error" }
+```
+
+This returns only logged items from the in memory stored log stream that have a level of "Error"
+
+### EXAMPLE 4
+```powershell
+Get-PnPTraceLog | Where-Object { $_.CorrelationId -eq "5a6206a0-6c83-4446-9d1b-38c14f93cb60" }
+```
+
+This returns only logged items from the in memory stored log stream that happened during the execution of a PnP PowerShell cmdlet with the provided correlation id. This is useful to find out what happened during the execution of a specific cmdlet. Mind that the correlation id is an unique identifier for the cmdlet execution assigned by PnP PowerShell and is not the same as the correlation id of a SharePoint operation.
+
+### EXAMPLE 5
+```powershell
+Get-PnPTraceLog | Sort-Object -Property EllapsedMilliseconds -Descending -Top 10 | Select EllapsedMilliseconds, Source, Message
+```
+
+Returns the 10 longest running operations from the in memory stored log stream. An operation is an action within the execution of a cmdlet. The output is sorted by the time it took to complete the operation with the longest execution at the top. The output shows the ellapsed time in milliseconds taken by a single operation, the cmdlet that was executed and the message that was logged.
+
+### EXAMPLE 6
+```powershell
+Get-PnPTraceLog | Group-Object -Property CorrelationId | ForEach-Object { [pscustomobject]@{ Started = ($_.Group | Select -First 1).TimeStamp; Ended = ($_.Group | Select -Last 1).TimeStamp; Cmdlet = $_.Group[0].Source; TimeTaken = ($_.Group | Measure-Object -Property EllapsedMilliseconds -Sum).Sum; Logs = $_.Group }} | Sort-Object -Property TimeTaken -Descending -Top 5 | Select Started, Cmdlet, TimeTaken
+```
+
+Returns the top 5 longest running cmdlets from the in memory stored log stream. The output is sorted by the TimeTaken property in descending order which shows the total execution time of a single cmdlet. The output contains the time the cmdlet started executing, the cmdlet that was executed and the total time it took to execute the cmdlet. From there it is easy to examine all the individual logs collected during the execution of that single cmdlet.
+
+## PARAMETERS
+
+### -Path
+The path to the log file. If not provided, the cmdlet will return the in memory log stream.
+
+Note that you cannot read from a log file if it is currently in use to write to. In this case, you would first have to stop logging to it using [Stop-PnPTraceLog](Stop-PnPTraceLog.md) and then read the log file.
+
+```yaml
+Type: String
+Parameter Sets: Log from file
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True
+Accept wildcard characters: False
+```
+
+### -Verbose
+When provided, additional debug statements will be shown while executing the cmdlet.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
+
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Start-PnPTraceLog.md

@@ -15,13 +15,26 @@ Starts log tracing
 ## SYNTAX
 
 ```powershell
-Start-PnPTraceLog [-Path <String>] [-Level <LogLevel>] [-AutoFlush <Boolean>] [-WriteToConsole <SwitchParameter>]
+Start-PnPTraceLog [-Path <String>] [-Level <LogLevel>] [-AutoFlush <Boolean>] [-WriteToConsole <SwitchParameter>] [-WriteToLogStream <SwitchParameter>]
 ```
 
-
 ## DESCRIPTION
 Starts .NET tracelogging. Many cmdlets output detailed trace information when executed. Turn on the trace log with this cmdlet, optionally specify the level. By default the level is set to 'Information', but you will receive more detail by setting the level to 'Debug'.
 
+You can look at the logged data using [Get-PnPTraceLog](Get-PnPTraceLog.md).
+
+The logged data contains the following information in the following order:
+
+- Timestamp
+- Source
+- Thread ID
+- Log level
+- Message
+- Elapsed time in milliseconds since the last log entry for the same cmdlet execution
+- Correlation ID which is an unique identifier per executed cmdlet so you can filter the log for everything logged during a specific cmdlet execution
+
+Beware that the logged data can be quite verbose, especially when the level is set to 'Debug'. When logging in memory, it can take up a lot of memory. When logging to a file, it can take up a lot of disk space. So be careful when using this in production environments and only use it when you need to troubleshoot something or are aware of the consequences.
+
 ## EXAMPLES
 
 ### EXAMPLE 1
@@ -38,12 +51,19 @@ Start-PnPTraceLog -Path ./TraceOutput.txt -Level Debug
 
 This turns on trace logging to the file 'TraceOutput.txt' and will capture all events.
 
+### EXAMPLE 3
+```powershell
+Start-PnPTraceLog -WriteToConsole -WriteToLogStream -Level Debug
+```
+
+This turns on trace logging to the console and in memory stream in which you are running your PowerShell script and will capture all events.
+
 ### EXAMPLE 3
 ```powershell
 Start-PnPTraceLog -WriteToConsole -Level Debug
 ```
 
-This turns on trace logging to console in which you are running your PowerShell script and will capture all events.
+This turns on trace logging to the console in which you are running your PowerShell script and will capture all events.
 
 ## PARAMETERS
 
@@ -104,6 +124,20 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -WriteToLogStream
+Write the trace log to the in memory stream. Use [Get-PnPTraceLog](Get-PnPTraceLog.md) to read the log stream.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ## RELATED LINKS
 
 [Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

documentation/Stop-PnPTraceLog.md

@@ -10,17 +10,19 @@ online version: https://pnp.github.io/powershell/cmdlets/Set-PnPTraceLog.html
 # Stops-PnPTraceLog
 
 ## SYNOPSIS
-Stops log tracing and flushes the log buffer if any items in there.
+Stops all log tracing and flushes the log buffer if any items in there.
 
 ## SYNTAX
 
 ```powershell
-Stop-PnPTraceLog
+Stop-PnPTraceLog [-StopFileLogging <SwitchParameter>] [-StopConsoleLogging <SwitchParameter>] [-StopLogStreamLogging <SwitchParameter>] [-Verbose]
 ```
 
-
 ## DESCRIPTION
-Stops .NET tracelogging. Many cmdlets output detailed trace information when executed. Turn on the trace log with Start-PnPTraceLog, optionally specify the level. By default the level is set to 'Information', but you will receive more detail by setting the level to 'Debug'.
+Stops PnP PowerShell tracelogging to specific targets. By default, all logging is stopped. You can use the parameters to stop specific logging targets only.
+
+You can turn on the trace log with [Start-PnPTraceLog](Start-PnPTraceLog.md).
+You can look at the logged data using [Get-PnPTraceLog](Get-PnPTraceLog.md).
 
 ## EXAMPLES
 
@@ -29,9 +31,61 @@ Stops .NET tracelogging. Many cmdlets output detailed trace information when exe
 Stop-PnPTraceLog
 ```
 
-This turns off trace logging 
+This turns off all trace logging
 
-## RELATED LINKS
+## EXAMPLES
+
+### EXAMPLE 2
+```powershell
+Stop-PnPTraceLog -StopFileLogging -StopConsoleLogging
+```
+
+This turns off trace logging to file and console, but keeps the other logging options active.
+
+## PARAMETERS
+
+### -StopConsoleLogging
+Allows you to specifically stop logging to the console while keeping the other logging options active.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
 
-[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
+Required: False
+Position: Named
+Default value: True
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -StopFileLogging
+Allows you to specifically stop logging to a file while keeping the other logging options active.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: True
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -StopLogStreamLogging
+Allows you to specifically stop logging to the in memory log stream while keeping the other logging options active.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+
+Required: False
+Position: Named
+Default value: True
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+## RELATED LINKS
 
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)