Add documentation for exceptions history feature (#4901)

cspell.json

@@ -26,6 +26,7 @@
         "codespaces",
         "configurator",
         "coreclr",
+        "cctor",
         "darc",
         "dbug",
         "disambiguator",

documentation/README.md

@@ -29,6 +29,7 @@ When running a dotnet application, differences in diverse local and production e
     - [`/operations`](./api/operations.md)
     - [`/collectionrules`](./api/collectionrules.md)
     - [`/stacks`](./api/stacks.md)
+    - [`/exceptions`](./api/exceptions.md)
 - [Configuration](./configuration/README.md)
     - [JSON Schema](./schema.json)
 - [Authentication](./authentication.md)

documentation/api/README.md

@@ -18,6 +18,7 @@ The following are the root routes on the HTTP API surface.
 | [`/metrics`](metrics.md) | Captures metrics of a process in the Prometheus exposition format. | 6.0 |
 | [`/livemetrics`](livemetrics.md) | Captures live metrics of a process. | 6.0 |
   [`/stacks`](stacks.md) | Gets the current callstacks of all .NET threads. | 8.0 Preview 7 |
+  [`/exceptions`](exceptions.md) | Gets a history of first chance exceptions from the default process. | 8.0 Preview 7 |
 | [`/logs`](logs.md) | Captures logs of processes. | 6.0 |
 | [`/info`](info.md) | Gets info about `dotnet monitor`. | 6.0 |
 | [`/operations`](operations.md) | Gets egress operation status or cancels operations. | 6.0 |

documentation/api/definitions.md

@@ -169,6 +169,20 @@ Object describing the list of event providers, keywords, event levels, and addit
 }
 ```
 
+## ExceptionInstance
+
+Object describing an exception instance.
+
+| Name | Type | Description |
+|---|---|---|
+| `id` | int | Unique identifier of the exception instance. |
+| `timestamp` | string | The UTC date and time in the ISO 8601 format of when the current exception was observed. |
+| `typeName` | string | The name of the current exception type, including the namespace and parent type names if it is a nested type. |
+| `moduleName` | string | The name of the module in which the current exception type exists. |
+| `message` | string | The message that describes the current exception. |
+| `innerExceptions` | int[] | The IDs of the [ExceptionInstance](#exceptioninstance)s that are the inner exceptions of the current exception. |
+| `callStack` | [CallStack](#callstack) | The call stack of the current exception, if it was thrown. |
+
 ## ExtensionMode
 
 Enumeration that describes additional execution modes supported by the extension; the ability to execute is assumed.

documentation/api/exceptions.md

@@ -0,0 +1,105 @@
+
+### Was this documentation helpful? [Share feedback](https://www.research.net/r/DGDQWXH?src=documentation%2Fapi%exceptions)
+
+# Exceptions History - Get
+
+Captures a history of first chance exceptions that were thrown in the [default process](defaultprocess.md).
+
+>**Note**: This feature is not enabled by default and requires configuration to be enabled. The [in-process features](./../configuration/in-process-features-configuration.md) must be enabled since the exceptions history feature uses shared libraries loaded into the target application for collecting the exception information.
+
+## HTTP Route
+
+```http
+GET /exceptions HTTP/1.1
+```
+
+## Host Address
+
+The default host address for these routes is `https://localhost:52323`. This route is only available on the addresses configured via the `--urls` command line parameter and the `DOTNETMONITOR_URLS` environment variable.
+
+## Authentication
+
+Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.
+
+Allowed schemes:
+- `Bearer`
+- `Negotiate` (Windows only, running as unelevated)
+
+## Responses
+
+| Name | Type | Description | Content Type |
+|---|---|---|---|
+| 200 OK | [ExceptionInstance](definitions.md#exceptioninstance)[] | JSON representation of first chance exceptions from the default process. | `application/x-ndjson` |
+| 200 OK | text | Text representation of first chance exceptions from the default process. | `text/plain` |
+| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
+
+## Examples
+
+### Sample Request
+
+```http
+GET /exceptions HTTP/1.1
+Host: localhost:52323
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
+Accept: text/plain
+```
+
+### Sample Response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: text/plain
+
+First chance exception at 2023-07-13T21:45:11.8056355Z
+System.InvalidOperationException: Operation is not valid due to the current state of the object.
+   at WebApplication3.Pages.IndexModel+<GetData>d__3.MoveNext()
+   at System.Threading.ExecutionContext.RunInternal(System.Threading.ExecutionContext,System.Threading.ContextCallback,System.Object)
+   at System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TStateMachine].MoveNext(System.Threading.Thread)
+   at System.Runtime.CompilerServices.YieldAwaitable+YieldAwaiter+<>c.<OutputCorrelationEtwEvent>b__6_0(System.Action,System.Threading.Tasks.Task)
+   at System.Threading.ThreadPoolWorkQueue.Dispatch()
+   at System.Threading.PortableThreadPool+WorkerThread.WorkerThreadStart()
+
+First chance exception at 2023-07-13T21:46:18.7530773Z
+System.ObjectDisposedException: Cannot access a disposed object.
+Object name: 'System.Net.Sockets.NetworkStream'.
+   at System.ThrowHelper.ThrowObjectDisposedException(System.Object)
+   at System.ObjectDisposedException.ThrowIf(System.Boolean,System.Object)
+   at System.Net.Sockets.NetworkStream.ReadAsync(System.Memory`1[[System.Byte, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]][System.Byte],System.Threading.CancellationToken)
+   at System.Net.Http.HttpConnection+<<EnsureReadAheadTaskHasStarted>g__ReadAheadWithZeroByteReadAsync|43_0>d.MoveNext()
+   at System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TStateMachine].ExecutionContextCallback(System.Object)
+   at System.Threading.ExecutionContext.RunInternal(System.Threading.ExecutionContext,System.Threading.ContextCallback,System.Object)
+   at System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TStateMachine].MoveNext(System.Threading.Thread)
+   at System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1[System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder`1+AsyncStateMachineBox`1+TStateMachine].MoveNext()
+   at System.Net.Sockets.SocketAsyncEventArgs+<>c.<.cctor>b__176_0(System.UInt32,System.UInt32,System.Threading.NativeOverlapped*)
+   at System.Threading.PortableThreadPool+IOCompletionPoller+Callback.Invoke(System.Threading.PortableThreadPool+IOCompletionPoller+Event)
+   at System.Threading.ThreadPoolTypedWorkItemQueue`2[System.Threading.ThreadPoolTypedWorkItemQueue`2+T,System.Threading.ThreadPoolTypedWorkItemQueue`2+TCallback].System.Threading.IThreadPoolWorkItem.Execute()
+   at System.Threading.ThreadPoolWorkQueue.Dispatch()
+   at System.Threading.PortableThreadPool+WorkerThread.WorkerThreadStart()
+```
+
+### Sample Request
+
+```http
+GET /exceptions HTTP/1.1
+Host: localhost:52323
+Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
+Accept: application/x-ndjson
+```
+
+### Sample Response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/x-ndjson
+
+{"id":2,"timestamp":"2023-07-13T21:45:11.8056355Z","typeName":"System.InvalidOperationException","moduleName":"System.Private.CoreLib.dll","message":"Operation is not valid due to the current state of the object.","innerExceptions":[],"callStack":{"threadId":4768,"threadName":null,"frames":[{"methodName":"MoveNext","parameterTypes":[],"className":"WebApplication3.Pages.IndexModel\u002B\u003CGetData\u003Ed__3","moduleName":"WebApplication3.dll"},{"methodName":"RunInternal","parameterTypes":["System.Threading.ExecutionContext","System.Threading.ContextCallback","System.Object"],"className":"System.Threading.ExecutionContext","moduleName":"System.Private.CoreLib.dll"},{"methodName":"MoveNext","parameterTypes":["System.Threading.Thread"],"className":"System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601[System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTStateMachine]","moduleName":"System.Private.CoreLib.dll"},{"methodName":"\u003COutputCorrelationEtwEvent\u003Eb__6_0","parameterTypes":["System.Action","System.Threading.Tasks.Task"],"className":"System.Runtime.CompilerServices.YieldAwaitable\u002BYieldAwaiter\u002B\u003C\u003Ec","moduleName":"System.Private.CoreLib.dll"},{"methodName":"Dispatch","parameterTypes":[],"className":"System.Threading.ThreadPoolWorkQueue","moduleName":"System.Private.CoreLib.dll"},{"methodName":"WorkerThreadStart","parameterTypes":[],"className":"System.Threading.PortableThreadPool\u002BWorkerThread","moduleName":"System.Private.CoreLib.dll"}]}}
+{"id":3,"timestamp":"2023-07-13T21:46:18.7530773Z","typeName":"System.ObjectDisposedException","moduleName":"System.Private.CoreLib.dll","message":"Cannot access a disposed object.\r\nObject name: \u0027System.Net.Sockets.NetworkStream\u0027.","innerExceptions":[],"callStack":{"threadId":15912,"threadName":null,"frames":[{"methodName":"ThrowObjectDisposedException","parameterTypes":["System.Object"],"className":"System.ThrowHelper","moduleName":"System.Private.CoreLib.dll"},{"methodName":"ThrowIf","parameterTypes":["System.Boolean","System.Object"],"className":"System.ObjectDisposedException","moduleName":"System.Private.CoreLib.dll"},{"methodName":"ReadAsync","parameterTypes":["System.Memory\u00601[[System.Byte, System.Private.CoreLib, Version=8.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e]][System.Byte]","System.Threading.CancellationToken"],"className":"System.Net.Sockets.NetworkStream","moduleName":"System.Net.Sockets.dll"},{"methodName":"MoveNext","parameterTypes":[],"className":"System.Net.Http.HttpConnection\u002B\u003C\u003CEnsureReadAheadTaskHasStarted\u003Eg__ReadAheadWithZeroByteReadAsync|43_0\u003Ed","moduleName":"System.Net.Http.dll"},{"methodName":"ExecutionContextCallback","parameterTypes":["System.Object"],"className":"System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601[System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTStateMachine]","moduleName":"System.Private.CoreLib.dll"},{"methodName":"RunInternal","parameterTypes":["System.Threading.ExecutionContext","System.Threading.ContextCallback","System.Object"],"className":"System.Threading.ExecutionContext","moduleName":"System.Private.CoreLib.dll"},{"methodName":"MoveNext","parameterTypes":["System.Threading.Thread"],"className":"System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601[System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTStateMachine]","moduleName":"System.Private.CoreLib.dll"},{"methodName":"MoveNext","parameterTypes":[],"className":"System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601[System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTResult,System.Runtime.CompilerServices.AsyncTaskMethodBuilder\u00601\u002BAsyncStateMachineBox\u00601\u002BTStateMachine]","moduleName":"System.Private.CoreLib.dll"},{"methodName":"\u003C.cctor\u003Eb__176_0","parameterTypes":["System.UInt32","System.UInt32","System.Threading.NativeOverlapped*"],"className":"System.Net.Sockets.SocketAsyncEventArgs\u002B\u003C\u003Ec","moduleName":"System.Net.Sockets.dll"},{"methodName":"Invoke","parameterTypes":["System.Threading.PortableThreadPool\u002BIOCompletionPoller\u002BEvent"],"className":"System.Threading.PortableThreadPool\u002BIOCompletionPoller\u002BCallback","moduleName":"System.Private.CoreLib.dll"},{"methodName":"System.Threading.IThreadPoolWorkItem.Execute","parameterTypes":[],"className":"System.Threading.ThreadPoolTypedWorkItemQueue\u00602[System.Threading.ThreadPoolTypedWorkItemQueue\u00602\u002BT,System.Threading.ThreadPoolTypedWorkItemQueue\u00602\u002BTCallback]","moduleName":"System.Private.CoreLib.dll"},{"methodName":"Dispatch","parameterTypes":[],"className":"System.Threading.ThreadPoolWorkQueue","moduleName":"System.Private.CoreLib.dll"},{"methodName":"WorkerThreadStart","parameterTypes":[],"className":"System.Threading.PortableThreadPool\u002BWorkerThread","moduleName":"System.Private.CoreLib.dll"}]}}
+```
+
+## Supported Runtimes
+
+| Operating System | Runtime Version |
+|---|---|
+| Windows | .NET 6+ |
+| Linux | .NET 6+ |
+| MacOS | .NET 6+ |

documentation/configuration/in-process-features-configuration.md

@@ -7,6 +7,7 @@ First Available: 8.0 Preview 7
 Some features of `dotnet monitor` require loading libraries into target applications. These libraries ship with `dotnet monitor` and are provisioned to be available to target applications using the `DefaultSharedPath` option in the [storage configuration](./storage-configuration.md) section. The following features require these in-process libraries to be used:
 
 - [Call Stacks](#call-stacks)
+- [Exceptions History](#exceptions-history)
 
 Because these libraries are loaded into the target application (they are not loaded into `dotnet monitor`), they may have performance impact on memory and CPU utilization in the target application. These features are off by default and may be enabled via the `InProcessFeatures` configuration section.
 
@@ -108,9 +109,81 @@ Similarly, the call stacks feature can be individually disabled by setting the s
   <summary>Kubernetes Environment Variables</summary>
   
   ```yaml
-  - name: InProcessFeatures__Enabled
+  - name: DotnetMonitor_InProcessFeatures__Enabled
     value: "true"
   - name: DotnetMonitor_InProcessFeatures__CallStacks__Enabled
     value: "false"
   ```
 </details>
+
+## Exceptions History
+
+The exceptions history feature is individually enabled by setting the `Enabled` property of the `Exceptions` section to `true`:
+
+<details>
+  <summary>JSON</summary>
+
+  ```json
+  {
+    "InProcessFeatures": {
+      "Exceptions": {
+        "Enabled": true
+      }
+    }
+  }
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes ConfigMap</summary>
+  
+  ```yaml
+  InProcessFeatures__Exceptions__Enabled: "true"
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes Environment Variables</summary>
+  
+  ```yaml
+  - name: DotnetMonitor_InProcessFeatures__Exceptions__Enabled
+    value: "true"
+  ```
+</details>
+
+Similarly, the exceptions history feature can be individually disabled by setting the same property to `false`:
+
+<details>
+  <summary>JSON</summary>
+
+  ```json
+  {
+    "InProcessFeatures": {
+      "Enabled": true,
+      "Exceptions": {
+        "Enabled": false
+      }
+    }
+  }
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes ConfigMap</summary>
+  
+  ```yaml
+  InProcessFeatures__Enabled: "true"
+  InProcessFeatures__Exceptions__Enabled: "false"
+  ```
+</details>
+
+<details>
+  <summary>Kubernetes Environment Variables</summary>
+  
+  ```yaml
+  - name: DotnetMonitor_InProcessFeatures__Enabled
+    value: "true"
+  - name: DotnetMonitor_InProcessFeatures__Exceptions__Enabled
+    value: "false"
+  ```
+</details>

src/Tools/dotnet-monitor/Exceptions/ExceptionsOperation.cs

@@ -103,10 +103,6 @@ namespace Microsoft.Diagnostics.Tools.Monitor.Exceptions
                 writer.WriteString("moduleName", instance.ModuleName);
                 writer.WriteString("message", instance.Message);
 
-                writer.WriteStartObject("callStack");
-                writer.WriteNumber("threadId", instance.CallStack.ThreadId);
-                writer.WriteString("threadName", instance.CallStack.ThreadName);
-
                 writer.WriteStartArray("innerExceptions");
                 foreach (ulong innerExceptionId in instance.InnerExceptionIds)
                 {
@@ -116,6 +112,10 @@ namespace Microsoft.Diagnostics.Tools.Monitor.Exceptions
                 }
                 writer.WriteEndArray();
 
+                writer.WriteStartObject("callStack");
+                writer.WriteNumber("threadId", instance.CallStack.ThreadId);
+                writer.WriteString("threadName", instance.CallStack.ThreadName);
+
                 writer.WriteStartArray("frames");
 
                 foreach (var frame in instance.CallStack.Frames)