Added and updated documentation

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
 
 ### 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,93 @@
+---
+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. 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
+
+### 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.
+
+## PARAMETERS
+
+### -Path
+The path to the log file. If not provided, the cmdlet will return the in memory log stream.
+
+```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

@@ -20,7 +20,7 @@ Stop-PnPTraceLog
 
 
 ## 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. Turn on the trace log with [Start-PnPTraceLog](Start-PnPTraceLog.md). Look at the logged data using [Get-PnPTraceLog](Get-PnPTraceLog.md).
 
 ## EXAMPLES
 
@@ -33,5 +33,4 @@ This turns off trace logging
 
 ## RELATED LINKS
 
-[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)
-
+[Microsoft 365 Patterns and Practices](https://aka.ms/m365pnp)

src/Commands/Base/BasePSCmdlet.cs

@@ -21,7 +21,7 @@ public class BasePSCmdlet : PSCmdlet
         /// </summary>
         protected override void BeginProcessing()
         {
-            LogDebug("Cmdlet execution started");
+            LogDebug($"Cmdlet execution started for {MyInvocation.MyCommand.Name}");
             base.BeginProcessing();
 
             CheckForDeprecationAttributes();
@@ -67,7 +67,7 @@ protected override void ProcessRecord()
         protected override void EndProcessing()
         {
             base.EndProcessing();
-            LogDebug("Cmdlet execution done");
+            LogDebug($"Cmdlet execution done for {MyInvocation.MyCommand.Name}");
         }
 
         /// <summary>

src/Commands/Base/ClearTraceLog.cs

@@ -12,7 +12,7 @@ protected override void ProcessRecord()
         {
             if (Trace.Listeners[LogStreamListener.DefaultListenerName] is not LogStreamListener logStreamListener)
             {
-                LogWarning("Log stream listener named {LogStreamListener.DefaultLogStreamListenerName} not found. No entries cleared.");
+                LogWarning($"Log stream listener named {LogStreamListener.DefaultListenerName} not found. No entries cleared.");
             }
             else
             {

src/Commands/Base/ConnectOnline.cs

@@ -407,12 +407,12 @@ protected void Connect(ref CancellationToken cancellationToken)
                 try
                 {
                     newConnection.Context.ExecuteQueryRetry();
-                    LogDebug($"Site at {Url} exists");
+                    LogInformational($"Site at {Url} exists");
                 }
                 catch (System.Net.WebException e) when (e.Message.Contains("404"))
                 {
-                    LogDebug($"Site at {Url} does not exist");
-                    throw new PSInvalidOperationException($"The specified site {Url} does not exist", e);
+                    LogError($"Site at {Url} does not exist");
+                    //throw new PSInvalidOperationException($"The specified site {Url} does not exist", e);
                 }
                 catch (TargetInvocationException tex)
                 {