## File: documentation/api/collectionrules.md

# Collection Rules

First Available: 6.3

The `/collectionrules` route reports the state of configured collection rules.

> [!NOTE]
> Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.

| Operation | Description |
|---|---|
| [Get Collection Rules](collectionrules-get.md) | Get the detailed state of the specified collection rule for all processes or for the specified process. |
| [List Collection Rules](collectionrules-list.md) | Get the basic state of all collection rules for all processes or for the specified process. |

---

## File: documentation/api/collectionrules-get.md

# Collection Rules - Get

First Available: 6.3

Get the detailed state of the specified collection rule for all processes or for the specified process.

## HTTP Route

```http
GET /collectionrules/{collectionrulename}?pid={pid}&uid={uid}&name={name} HTTP/1.1
```

> [!NOTE]
> Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.

## 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.

## URI Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `collectionrulename` | path | true | string | The name of the collection rule for which a detailed description should be provided. |
| `pid` | query | false | int | The ID of the process. |
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
| `name` | query | false | string | The name of the process. |

See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.

If none of `pid`, `uid`, or `name` are specified, the detailed description of the collection rule for the [default process](defaultprocess.md) will be provided. Attempting to get the detailed description from the default process when the default process cannot be resolved will fail.

## 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 | [CollectionRuleDetailedDescription](definitions.md#collectionruledetaileddescription-63) | The detailed information about the current state of the specified collection rule. | `application/json` |
| 400 Bad Request | [ValidationProblemDetails](definitions.md#validationproblemdetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |

## Examples

### Sample Request

```http
GET /collectionrules?pid=21632 HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

or

```http
GET /collectionrules?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "state":"Running",
  "stateReason":"This collection rule is active and waiting for its triggering conditions to be satisfied.",
  "lifetimeOccurrences":0,
  "slidingWindowOccurrences":0,
  "actionCountLimit":2,
  "actionCountSlidingWindowDurationLimit":"00:01:00",
  "slidingWindowDurationCountdown":null,
  "ruleFinishedCountdown":"00:03:00"
}
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET 5+ |
| Linux | .NET 5+ |
| MacOS | .NET 5+ |

## Additional Notes

### When to use `pid` vs `uid`

See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.

---

## File: documentation/api/collectionrules-list.md

# Collection Rules - List

First Available: 6.3

Get the basic state of all collection rules for all processes or for the specified process.

## HTTP Route

```http
GET /collectionrules?pid={pid}&uid={uid}&name={name} HTTP/1.1
```

> [!NOTE]
> Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.

## 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.

## URI Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pid` | query | false | int | The ID of the process. |
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
| `name` | query | false | string | The name of the process. |

See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.

If none of `pid`, `uid`, or `name` are specified, the state of collection rules for the [default process](defaultprocess.md) will be provided. Attempting to get the state of collection rules from the default process when the default process cannot be resolved will fail.

## 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 | map (of [CollectionRuleDescription](definitions.md#collectionruledescription-63)) | The basic information about the current state of the configured collection rules. | `application/json` |
| 400 Bad Request | [ValidationProblemDetails](definitions.md#validationproblemdetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |

## Examples

### Sample Request

```http
GET /collectionrules?pid=21632 HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

or

```http
GET /collectionrules?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "MyCollectionRule": {
    "state":"Running",
    "stateReason":"This collection rule is active and waiting for its triggering conditions to be satisfied.",
  }
}
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET 5+ |
| Linux | .NET 5+ |
| MacOS | .NET 5+ |

## Additional Notes

### When to use `pid` vs `uid`

See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.

---

## File: documentation/api/defaultprocess.md

# Default Process

When using APIs to capture diagnostic artifacts, typically a `pid`, `uid`, or `name` is provided to perform the operation on a specific process. However, these parameters may be omitted if `dotnet monitor` is able to resolve a default process.

The tool is able to resolve a default process if there is one and only one observable process. If there are no processes or there is more than one process, any API that allows operating on the default process will fail when invoked.

---

## File: documentation/api/definitions.md

# Definitions

> [!NOTE]
> Some features are [experimental](./../experimental.md) and are denoted as `**[Experimental]**` in this document.

## CallStack

First Available: 8.0 Preview 7

| Name | Type | Description |
|---|---|---|
| `threadId` | int | The native thread id of the managed thread. |
| `threadName` | string | Optional name of the managed thread. |
| `frames` | [CallStackFrame](#callstackframe)[] | Managed frame for the thread at the time of collection. |

## CallStackFormat

First Available: 8.0 Preview 7

Enumeration that describes the output format of the collected call stacks.

| Name | Description |
|---|---|
| `Json` | Stacks are formatted in Json. See [CallStackResult](#callstackresult). |
| `PlainText` | Stacks are formatted in plain text. |
| `Speedscope` | Stacks are formatted in [speedscope](https://www.speedscope.app). Note that performance data is not present. |

## CallStackFrame

First Available: 8.0 Preview 7

| Name | Type | Description |
|---|---|---|
| `methodName` | string | Name of the method for this frame. This includes generic parameters. |
| `methodToken` | int | TypeDef token for the method. |
| `parameterTypes` | string[] | Array of parameter types. Empty array if none. Field does not exist when this information is not available. |
| `typeName` | string | Name of the class for this frame. This includes generic parameters. |
| `moduleName` | string | Name of the module for this frame. |
| `moduleVersionId` | guid | Unique identifier used to distinguish between two versions of the same module. An empty value: `00000000-0000-0000-0000-000000000000`. |
| `hidden`| bool |(8.1+ and 9.0+) Whether this frame has the [StackTraceHiddenAttribute](https://learn.microsoft.com/dotnet/api/system.diagnostics.stacktracehiddenattribute) and should be omitted from stack trace text. |

## CallStackResult

First Available: 8.0 Preview 7

| Name | Type | Description |
|---|---|---|
| `stacks` | [CallStack](#callstack)[] | List of all managed stacks at the time of collection. |

## CollectionRuleDescription

First Available: 6.3

Object describing the basic state of a collection rule for the executing instance of `dotnet monitor`.

| Name | Type | Description |
|---|---|---|
| State | [CollectionRuleState](#collectionrulestate) | Indicates what state the collection rule is in for the current process. |
| StateReason | string | Human-readable explanation for the current state of the collection rule. |

## CollectionRuleDetailedDescription

First Available: 6.3

Object describing the detailed state of a collection rule for the executing instance of `dotnet monitor`.

| Name | Type | Description |
|---|---|---|
| State | [CollectionRuleState](#collectionrulestate) | Indicates what state the collection rule is in for the current process. |
| StateReason | string | Human-readable explanation for the current state of the collection rule. |
| LifetimeOccurrences | int | The number of times the trigger has executed for a process in its lifetime. |
| SlidingWindowOccurrences | int | The number of times the trigger has executed within the current sliding window. |
| ActionCountLimit | int | The number of times the action list may be executed before being throttled. |
| ActionCountSlidingWindowDurationLimit | TimeSpan? | The sliding window of time to consider whether the action list should be throttled based on the number of times the action list was executed. Executions that fall outside the window will not count toward the limit specified in the ActionCount setting. If not specified, all action list executions will be counted for the entire duration of the rule. |
| SlidingWindowDurationCountdown | TimeSpan? | The amount of time remaining before the collection rule will no longer be throttled. |
| RuleFinishedCountdown | TimeSpan? | The amount of time remaining before the rule will stop monitoring a process after it has been applied to a process. If not specified, the rule will monitor the process with the trigger indefinitely. |

## CollectionRuleState

First Available: 6.3

Enumeration that describes the current state of the collection rule.

| Name | Description |
|---|---|
| `Running` | Indicates that the collection rule is active and waiting for its triggering conditions to be satisfied. |
| `ActionExecuting` | Indicates that the collection has had its triggering conditions satisfied and is currently executing its action list. |
| `Throttled` | Indicates that the collection rule is temporarily throttled because the ActionCountLimit has been reached within the ActionCountSlidingWindowDuration. |
| `Finished` | Indicates that the collection rule has completed and will no longer trigger. |

## CapturedMethod

First Available: 9.0 Preview 4

Object describing a captured method and its parameters.

| Name | Type | Description |
|---|---|---|
| `activityId` | string? | An identifier for the current activity at the time of the capture. For more information see [Activity.Id](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity.id).|
| `activityIdFormat` | string | The activity Id format. For more information see [Activity.IdFormat](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activity.idformat).|
| `threadId` | int | The managed thread id where the method was called.|
| `timestamp` | DateTime | Time when the method call was captured. |
| `moduleName` | string | The method module name. |
| `typeName` | string | The method type name. |
| `methodName` | string | The method name. |
| `parameters` | [CapturedParameter](#capturedparameter)[] | Array of captured parameters. |
| `methodToken` | int |(9.1+) TypeDef token for the method. |
| `moduleVersionId` | guid |(9.1+) Unique identifier used to distinguish between two versions of the same module. An empty value: `00000000-0000-0000-0000-000000000000`. |

## CapturedParameter

First Available: 9.0 Preview 4

Object describing a captured parameter.

| Name | Type | Description |
|---|---|---|
| `parameterName` | string | The parameter name. |
| `value` | string? | The parameter value. |
| `typeName` | string | The parameter type name. |
| `moduleName` | string | The parameter type module name. |
| `evalFailReason` | string | The reason why evaluation failed. If missing the evaluation was successful. |

## CaptureParametersConfiguration

First Available: 8.0 RC 1

Object describing the list of methods to capture parameters for.

| Name | Type | Description |
|---|---|---|
| `methods` | [MethodDescription](#methoddescription)[] | Array of methods to capture parameters for. |
| `useDebuggerDisplayAttribute` | bool | Determines if parameters should be formatted using their [`DebuggerDisplayAttribute`](https://learn.microsoft.com/dotnet/api/system.diagnostics.debuggerdisplayattribute) if available and supported. Expressions in attributes may consist of properties, fields, methods without parameters, or any combination of these. |
| `captureLimit` | int | The number of times to capture parameters before stopping. If the specified duration elapses the operation will stop even if the capture limit is not yet reached. Note that parameters may continue to be captured for a short amount of time after this limit is reached. |

## DotnetMonitorInfo

Object describing diagnostic/automation information about the executing instance of `dotnet monitor`.

| Name | Type | Description |
|---|---|---|
| Version | string | The current version of `dotnet monitor`. |
| RuntimeVersion | string | The version of the dotnet runtime. |
| DiagnosticPortMode | DiagnosticPortConnectionMode | Indicates whether `dotnet monitor` is in `connect` mode or `listen` mode. |
| DiagnosticPortName | string | The name of the named pipe or unix domain socket to use for connecting to the diagnostic server. |
| Capabilities | [MonitorCapability](#monitorcapability)[] |(9.1+) The capabilities provided by `dotnet monitor`. |

## DumpType

Enumeration that describes the type of information to capture in a managed dump.

| Name | Description |
|---|---|
| `Mini` | A small dump containing module lists, thread lists, exception information, and all stacks. |
| `Full` | The largest dump containing all memory including the module images. |
| `Triage` | A small dump containing only stacks for each thread. |
| `WithHeap` | A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images. |

## EventMetricsConfiguration

Describes custom metrics.

| Name | Type | Description |
|---|---|---|
| `includeDefaultProviders` | bool | Determines if the default counter providers should be used (such as System.Runtime). |
| `providers` | [EventMetricsProvider](#eventmetricsprovider)[] | Array of counter providers for metrics to collect. |
| `meters` | [EventMetricsMeter](#eventmetricsmeter)[] | (7.1+) Array of meters for metrics to collect. |

## EventMetricsMeter

| Name | Type | Description |
|---|---|---|
| `meterName` | string | The name of the meter. Note this is case-insensitive. |
| `instrumentNames` | string[] | Array of instruments for metrics to collect for the specified meter. These are case-sensitive. |

## EventMetricsProvider

| Name | Type | Description |
|---|---|---|
| `providerName` | string | The name of the metric provider. Note this is case-insensitive. |
| `counterNames` | string[] | Array of providers for metrics to collect. These are case-sensitive. |

## EventProvider

Object describing which events to capture from a single event provider with keywords and event levels.

| Name | Type | Description |
|---|---|---|
| Name | string | The name of the provider from which to capture events. See [Well-known Event Providers](https://docs.microsoft.com/dotnet/core/diagnostics/well-known-event-providers) for commonly used event providers. |
| Keywords | string | Keyword flags used to enable groups of events. Keyword flags are provider specific. May be specified as a 'stringified' integer or a hexadecimal-encoded integer starting with `0x`. |
| EventLevel | [EventLevel](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventlevel) | The level of the events to collect. |
| Arguments | map (of string) | Additional arguments to the event provider. Names and values are event provider specific. |

## EventProvidersConfiguration

Object describing the list of event providers, keywords, event levels, and additional parameters for capturing a trace.

| Name | Type | Description |
|---|---|---|
| Providers | [EventProvider](#eventprovider)[] | List of event providers from which to capture events. At least one event provider must be specified. |
| RequestRundown | bool | The runtime may provide additional type information for certain types of events after the trace session is ended. This additional information is known as rundown events. Without this information, some events may not be parsable into useful information. Default is `true`. |
| BufferSizeInMB | int | The size (in megabytes) of the event buffer used in the runtime. If the event buffer is filled, events produced by event providers may be dropped until the buffer is cleared. Increase the buffer size to mitigate this or pair down the list of event providers, keywords, and level to filter out extraneous events. Default is `256`. Min is `1`. Max is `1024`. |

### Example

```json
{
    "Providers": [{
        "Name": "Microsoft-DotNETCore-SampleProfiler",
        "EventLevel": "Informational"
    },{
        "Name": "Microsoft-Windows-DotNETRuntime",
        "EventLevel": "Informational",
        "Keywords": "0x14C14FCCBD"
    }],
    "BufferSizeInMB": 1024
}
```

## ExceptionFilter

Object describing attributes of an exception to use for filtering. To be filtered, an exception must match **all** provided fields (e.g. if `typeName` and `exceptionType` are provided, the top frame of the exception's call stack must have that class name and the exception must be that type).

| Name | Type | Description |
|---|---|---|
| `methodName` | string | The name of the top stack frame's method. |
| `typeName` | string | The name of the top stack frame's type. |
| `moduleName` | string | The name of the top stack frame's module. |
| `exceptionType` | string | The type of the exception (e.g. "System.ObjectDisposedException"). |

## ExceptionsConfiguration

Object describing which exceptions should be included/excluded. To be filtered, an exception must match **any** of the `ExceptionConfiguration` in the list (e.g. if `include` is a list of three `ExceptionConfiguration`, exceptions only need to match one of the three in order to be included).

| Name | Type | Description |
|---|---|---|
| `include` | [ExceptionFilter[]](#exceptionfilter) | The list of exceptions to include in the filter - anything not listed in the filter will not be included in the results. |
| `exclude` | [ExceptionFilter[]](#exceptionfilter) | The list of exceptions to exclude in the filter - anything not listed in the filter will be included in the results. |

## 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. |
| `stack` | [CallStack](#callstack) | The call stack of the current exception, if it was thrown. |

## ExceptionFormat

First Available: 8.0 RC 1

Enumeration that describes the format to use when outputting exceptions.

| Name |
|---|
| `JsonSequence` |
| `NewlineDelimitedJson` |
| `PlainText` |

## ExtensionMode

Enumeration that describes additional execution modes supported by the extension; the ability to execute is assumed.

| Name |
|---|
| `Validate` |

## LogEntry

Object describing a log entry from a target process.

| Name | Type | Description |
|---|---|---|
| `Arguments` | map (of object) | The arguments of the format string of the log entry, including an entry for the original format string. |
| `Category` | string | The category of the log entry. |
| `EventId` | string | The event name of the EventId of the log entry. |
| `Exception` | string | If an exception is logged, this property contains the formatted message of the log entry. |
| `LogLevel` | string | The [LogLevel](#loglevel) of the log entry. |
| `Message` | string | If an exception is NOT logged, this property contains the formatted message of the log entry. |
| `Scopes` | map (of object) | The scope information associated with the log entry. |

### Example

If an application logged the following message:

```cs
ILogger<MyNamespace.MyClass> logger = loggerFactory.CreateLogger<MyNamespace.MyClass>();
logger.LogError(new EventId(7, "FailedAfterRetries"), "Failed to get resource after {attempts} attempts.", 5);
```

The above message would be reported as:

```json
{
    "LogLevel": "Error",
    "EventId": "FailedAfterRetries",
    "Category": "MyNamespace.MyClass",
    "Message": "Failed to get resource after 5 attempts.",
    "Scopes": {
        "RequestId": "8000000a-0004-fc00-b63f-84710c7967bb",
        "RequestPath": "/",
        "ActionId": "9524e18b-1bac-4d4c-88d7-68a753258b1c",
        "ActionName": "/Index"
    },
    "Arguments": {
        "attempts": "5",
        "{OriginalFormat}": "Failed to get resource after {attempts} attempts."
    }
}
```

## LogFormat

Enumeration that describes the format to use when outputting logs.

| Name |
|---|
| `JsonSequence` |
| `NewlineDelimitedJson` |
| `PlainText` |

## LogLevel

Enumeration that defines logging severity levels.

See [LogLevel](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.loglevel) documentation.

## LogsConfiguration

Object describing the default log level and filtering specifications for collecting logs.

| Name | Type | Description |
|---|---|---|
| `logLevel` | [LogLevel](#loglevel) | The default log level at which logs are collected. Default is `Warning`. |
| `filterSpecs` | map (of [LogLevel](#loglevel) or `null`) | A mapping of logger categories and the levels at which those categories should be collected. If level is set to `null`, collect category at the default level set in the `logLevel` property. |
| `useAppFilters` | bool | Collect logs for the categories and at the levels as specified by the [application-defined configuration](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/logging/#configure-logging). Default is `true`. |

### Example

The following configuration will collect logs for the Microsoft.AspNetCore.Hosting category at the Information level or higher.

```json
{
    "filterSpecs": {
        "Microsoft.AspNetCore.Hosting": "Information"
    },
    "useAppFilters": false
}
```

## MethodDescription

Object describing a method.

| Name | Type | Description |
|---|---|---|
| `moduleName`| string | The name of the module that the method belongs to. |
| `typeName` | string | The name of the type that the method belongs to. |
| `methodName` | string | The name of the method, not including parameters. |

## Metric

Object describing a metric from the application.

| Name | Type | Description |
|---|---|---|
| `name`| string | The unique name of this metric. |
| `displayName` | string | Friendly name for the metric. |
| `timestamp` | DateTime | Time when the metric was collected. |
| `provider` | string | The provider name for the metric. |
| `unit` | string | The unit for the metric. Can be null. |
| `counterType` | string | The type of metric. This is typically `Rate` or `Metric`. |
| `value` | double | The value of the metric. |

## MonitorCapability

First Available: 9.1

The name and enablement of a `dotnet monitor` capability.

| Name | Type | Description |
|---|---|---|
| `name`| string | The name of the capability. |
| `enabled` | bool | The enablement status of the capability. |

## OperationError

| Name | Type | Description |
|---|---|---|
| `code` | string | Error code representing the failure. |
| `message` | string | Detailed error message. |

## OperationProcessInfo

First Available: 6.3

The process on which the egress operation is performed.

| Name | Type | Description |
|---|---|---|
| `pid` | int | The ID of the process. |
| `uid` | guid | `.NET 5+` A value that uniquely identifies a runtime instance within a process.`.NET Core 3.1` An empty value: `00000000-0000-0000-0000-000000000000` |
| `name` | string | The name of the process. |

## OperationState

Status of the egress operation.

| Name | Description |
|---|---|
| `Running` | Operation has been started. This is the initial state. |
| `Cancelled` | The operation was cancelled by the user. |
| `Stopping` | The operation is in the process of stopping at the request of the user. |
| `Succeeded` | Egress operation has been successful. Querying the operation will return the location of the egressed artifact. |
| `Failed` | Egress operation failed. Querying the operation will return detailed error information. |

## OperationStatus

Detailed information about an operation.

| Name | Type | Description |
|---|---|---|
| `resourceLocation` | string | Resource location of the egressed artifact. This can be Uri or path depending on the egress provider. |
| `error` | [OperationError](#operationerror) | Detailed error message if the operation is in a `Failed` state. |
| `operationId` | guid | Unique identifier for the operation. |
| `createdDateTime` | datetime string | UTC DateTime string of when the operation was created. |
| `status` | [OperationState](#operationstate) | The current status of operation. |
| `egressProviderName` | string | (7.1+) The name of the egress provider that the artifact is being sent to. This will be null if the artifact is being sent directly back to the user from an HTTP request. |
| `isStoppable` | bool | (7.1+) Whether this operation can be gracefully stopped using [Stop Operation](operations-stop.md). Not all operations support being stopped. |
| `process` | [OperationProcessInfo](#operationprocessinfo) | (6.3+) The process on which the operation is performed. |
| `tags` | set (of string) | (7.1+) A set of user-readable identifiers for the operation. |

### Example

```json
{
    "resourceLocation": "https://example.blob.core.windows.net/dotnet-monitor/artifacts%2Fcore_20210721_062115",
    "error": null,
    "operationId": "67f07e40-5cca-4709-9062-26302c484f18",
    "createdDateTime": "2021-07-21T06:21:15.315861Z",
    "status": "Succeeded",
    "egressProviderName": "monitorBlob",
    "isStoppable": false,
    "process": {
        "pid": 21632,
        "uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b",
        "name": "dotnet"
    },
    "tags": [
        "tag1"
    ]
}
```

## OperationSummary

Summary state of an operation.

| Name | Type | Description |
|---|---|---|
| `operationId` | guid | Unique identifier for the operation. |
| `createdDateTime` | datetime string | UTC DateTime string of when the operation was created. |
| `status` | [OperationState](#operationstate) | The current status of operation. |
| `egressProviderName` | string | (7.1+) The name of the egress provider that the artifact is being sent to. This will be null if the artifact is being sent directly back to the user from an HTTP request. |
| `isStoppable` | bool | (7.1+) Whether this operation can be gracefully stopped using [Stop Operation](operations-stop.md). Not all operations support being stopped. |
| `process` | [OperationProcessInfo](#operationprocessinfo) | (6.3+) The process on which the operation is performed. |
| `tags` | set (of string) | (7.1+) A set of user-readable identifiers for the operation. |

### Example

```json
{
    "operationId": "67f07e40-5cca-4709-9062-26302c484f18",
    "createdDateTime": "2021-07-21T06:21:15.315861Z",
    "status": "Succeeded",
    "egressProviderName": null,
    "isStoppable": false,
    "process": {
        "pid": 21632,
        "uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b",
        "name": "dotnet"
    },
    "tags": [
        "tag1",
        "tag2"
    ]
}
```

## ProcessIdentifier

Object with process identifying information. The properties on this object describe identifying aspects for a found process; these values can be used in other API calls to perform operations on specific processes.

| Name | Type | Description |
|---|---|---|
| `name` | string | The name of the process. |
| `pid` | int | The ID of the process. |
| `uid` | guid | `.NET 5+` A value that uniquely identifies a runtime instance within a process.`.NET Core 3.1` An empty value: `00000000-0000-0000-0000-000000000000` |

The `uid` property is useful for uniquely identifying a process when it is running in an environment where the process ID may not be unique (e.g. multiple containers within a Kubernetes pod will have entrypoint processes with process ID 1).

The `name` property may not be a unique identifier if the application was built as a [framework-dependent executable](https://docs.microsoft.com/en-us/dotnet/core/deploying/#publish-framework-dependent). In this case, the name of the process is likely to be either `dotnet.exe` (Windows) or `dotnet` (non-Windows). Framework-dependent executables rely on a shared framework installation, which uses the `dotnet.exe` or `dotnet` executable to run the application.

### Example

```json
{
    "pid": 21632,
    "uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b"
}
```

## ProcessInfo

Object with detailed information about a specific process.

Some properties will have non-null values for processes that are running on .NET 5 or newer (denoted with `.NET 5+`). These properties will be null for runtime versions prior to .NET 5.

| Name | Type | Description |
|---|---|---|
| `pid` | int | The ID of the process. |
| `uid` | guid | `.NET 5+` A value that uniquely identifies a runtime instance within a process.`.NET Core 3.1` An empty value: `00000000-0000-0000-0000-000000000000` |
| `name` | string | The name of the process. |
| `commandLine` | string | The command line of the process (includes process path and arguments) |
| `operatingSystem` | string | `.NET 5+` The operating system on which the process is running (e.g. `windows`, `linux`, `macos`).`.NET Core 3.1` A value of `null`. |
| `processArchitecture` | string | `.NET 5+` The architecture of the process (e.g. `x64`, `x86`).`.NET Core 3.1` A value of `null`. |
| `managedEntryPointAssemblyName` | string | `9.1+` The name of the managed entry point assembly. The entry point assembly is typically the assembly that contains the `Program` class for the application. |

The `uid` property is useful for uniquely identifying a process when it is running in an environment where the process ID may not be unique (e.g. multiple containers within a Kubernetes pod will have entrypoint processes with process ID 1).

### Example

```json
{
    "pid": 21632,
    "uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b",
    "name": "dotnet",
    "commandLine": "\"C:\\Program Files\\dotnet\\dotnet.exe\" ConsoleApp1.dll",
    "operatingSystem": "Windows",
    "processArchitecture": "x64"
}
```
## TraceEventFilter

Object describing a filter for trace events.

| Name | Type | Description |
|---|---|---|
| `ProviderName` | string | The event provider that will produce the specified event. |
| `EventName` | string | The name of the event, which is a concatenation of the task name and opcode name, if any. The task and opcode names are separated by a '/'. If the event has no opcode, then the event name is just the task name. |
| `PayloadFilter` | map (of string) | (Optional) A mapping of event payload field names to their expected value. A subset of the payload fields may be specified. |


## TraceProfile

Enumeration that describes the type of diagnostic trace to capture. Each profile represents a list of event providers, event levels, and keywords.

| Name | Description |
|---|---|
| `Cpu` | Tracks CPU usage and general .NET runtime information. |
| `Http` | Tracks ASP[]().NET request handling and HttpClient requests. |
| `Logs` | Tracks log events emitted at the `Debug` [log level](https://docs.microsoft.com/dotnet/api/system.diagnostics.tracing.eventlevel) or higher. |
| `Metrics` | Tracks [event counters](https://docs.microsoft.com/en-us/dotnet/core/diagnostics/available-counters) from the `System.Runtime`, `Microsoft.AspNetCore.Hosting`, and `Grpc.AspNetCore.Server` event sources. |
| `GcCollect` | Tracks only garbage collection events, same as the `gc-collect` profile for `dotnet-trace`. |

## ValidationProblemDetails

Object for specifying errors and validation results based on https://tools.ietf.org/html/rfc7807

| Name | Type | Description |
|---|---|---|
| `detail` | string | An explanation specific to this occurrence of the problem. |
| `errors` | map (of string[]) | (Optional) The validation errors related to the request. |
| `extensions` | map (of object) | (Optional) Extension members containing additional information about the problem. |
| `instance` | string | (Optional) A URI reference that identifies the specific occurrence of the problem. |
| `status` | int | The HTTP status code generated by the origin server for this occurrence of the problem. |
| `title` | string | (Optional) A short summary of the problem type. |
| `type` | string | (Optional) A URI reference that identifies the problem type. |

### Example

```json
{
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "Providers": [
            "The Providers field is required."
        ]
    }
}
```

---

## File: documentation/api/dump.md

# Dump - Get

Captures a managed dump of a specified process without using a debugger.

> **Warning**: Capturing a dump of the process suspends the entire process while the dump is collected.

## HTTP Route

```http
GET /dump?pid={pid}&uid={uid}&name={name}&type={type}&egressProvider={egressProvider}&tags={tags} HTTP/1.1
```

> [!NOTE]
> Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.

## 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.

## URI Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pid` | query | false | int | The ID of the process. |
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
| `name` | query | false | string | The name of the process. |
| `type` | query | false | [DumpType](definitions.md#dumptype) | The type of dump to capture. Default value is `WithHeap` |
| `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected dump. When not specified, the dump is written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
| `tags` | query | false | string | (7.1+) A comma-separated list of user-readable identifiers for the operation. |

See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.

If none of `pid`, `uid`, or `name` are specified, a dump of the [default process](defaultprocess.md) will be captured. Attempting to capture a dump of the default process when the default process cannot be resolved will fail.

## 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 | stream | A managed dump of the process when no egress provider is specified. | `application/octet-stream` |
| 202 Accepted | | When an egress provider is specified, the artifact has begun being collected. | |
| 400 Bad Request | [ValidationProblemDetails](definitions.md#validationproblemdetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
| 429 Too Many Requests | | There are too many dump requests at this time. Try to request a dump at a later time. | |

> [!NOTE]
> **(7.1+)** Regardless if an egress provider is specified if the request was successful (response codes 200 or 202), the Location header contains the URI of the operation. This can be used to query the status of the operation or change its state.

## Examples

### Sample Request

```http
GET /dump?pid=21632&type=Full HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

or

```http
GET /dump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b&type=Full HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

### Sample Response

The managed dump containing all memory of the process, chunk encoded, is returned as the response body.

```http
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Location: localhost:52323/operations/67f07e40-5cca-4709-9062-26302c484f18
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET Core 3.1, .NET 5+ |
| Linux | .NET Core 3.1, .NET 5+ |
| MacOS | .NET 5+ |

> [!NOTE]
> For .NET 5, only ELF core dumps are supported on MacOS and require setting an environment variable in the application. Starting in .NET 6, dumps will be in the MachO format, and this environment variable is deprecated. See [Minidump Generation on OS X](https://github.com/dotnet/runtime/blob/main/docs/design/coreclr/botr/xplat-minidump-generation.md#os-x) for further details.

## Additional Notes

### When to use `pid` vs `uid`

See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.

### View the collected dump file

Dump files collected from this route can be analyzed using tools such as [dotnet-dump](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-dump) or Visual Studio.

---

## File: documentation/api/exceptions.md

# Exceptions History - Get

Captures a history of first chance exceptions that were thrown in the specified process.

> [!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?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider}&tags={tags} HTTP/1.1
```

> [!NOTE]
> Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.

## 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.

## URI Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pid` | query | false | int | The ID of the process. |
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
| `name` | query | false | string | The name of the process. |
| `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected exceptions. When not specified, the exceptions are written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
| `tags` | query | false | string | (7.1+) A comma-separated list of user-readable identifiers for the operation. |

See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.

If none of `pid`, `uid`, or `name` are specified, exceptions from the [default process](defaultprocess.md) will be captured. Attempting to capture exceptions from the default process when the default process cannot be resolved will fail.

## 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)[] | Newline-delimited JSON representation of first chance exceptions from the target process. | `application/x-ndjson` |
| 200 OK | [ExceptionInstance](definitions.md#exceptioninstance)[] | Separator-delimited JSON representation of first chance exceptions from the target process. | `application/json-seq` |
| 200 OK | text | Text representation of first chance exceptions from the target process. | `text/plain` |
| 202 Accepted | | When an egress provider is specified. | |
| 400 Bad Request | [ValidationProblemDetails](definitions.md#validationproblemdetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |

## Examples

### Sample Request

Collect exceptions from a specific process in plain text format:

```http
GET /exceptions?pid=21632 HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
Accept: text/plain
```

or

```http
GET /exceptions?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b 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.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

Collect exceptions from the default process in newline-delimited JSON format:

```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": [],
  "stack": {
    "threadId": 4768,
    "threadName": null,
    "frames": [
      {
        "methodName": "MoveNext",
        "methodToken": 100663639,
        "parameterTypes": [],
        "typeName": "WebApplication3.Pages.IndexModel\u002B\u003CGetData\u003Ed__3",
        "moduleName": "WebApplication3.dll",
        "moduleVersionId": "bf769014-c2e2-496a-93b7-76fbbcd04be5",
        "hidden": false
      },
      ... // see stacks.md
    ]
  }
}
{
  "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": [],
  "stack": {
    "threadId": 15912,
    "threadName": null,
    "frames": [
      {
        "methodName": "ThrowObjectDisposedException",
        "methodToken": 100663639,
        "parameterTypes": [
          "System.Object"
        ],
        "typeName": "System.ThrowHelper",
        "moduleName": "System.Private.CoreLib.dll",
        "moduleVersionId": "bf769014-c2e2-496a-93b7-76fbbcd04be5",
        "hidden": true
      },
      ... // see stacks.md
    ]
  }
}
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET 6+ |
| Linux | .NET 6+ |
| MacOS | .NET 6+ |

---

## File: documentation/api/exceptions-custom.md

# Exceptions History - Custom

Captures a history of first chance exceptions that were thrown in the specified process, with the ability to filter which exceptions are included in the response.

> [!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
POST /exceptions?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider}&tags={tags} 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.

## URI Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pid` | query | false | int | The ID of the process. |
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
| `name` | query | false | string | The name of the process. |
| `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected exceptions. When not specified, the exceptions are written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
| `tags` | query | false | string | (7.1+) A comma-separated list of user-readable identifiers for the operation. |

See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.

If none of `pid`, `uid`, or `name` are specified, exceptions from the [default process](defaultprocess.md) will be captured. Attempting to capture exceptions from the default process when the default process cannot be resolved will fail.

## Authentication

Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.

Allowed schemes:
- `Bearer`
- `Negotiate` (Windows only, running as unelevated)

## Request Body

A request body of type [ExceptionsConfiguration](definitions.md#exceptionsconfiguration) is required.

The expected content type is `application/json`.

## 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
POST /exceptions HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
Accept: text/plain
{
    "Exclude": [
        {
            "exceptionType": "System.InvalidOperationException"
        }
    ]
}
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: text/plain

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
POST /exceptions HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
Accept: text/plain
{
    "Include": [
        {
            "methodName": "MyExceptionMethod"
        }
    ]
}
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: text/plain

First chance exception at 2023-08-08T14:50:34.1039177Z
System.InvalidOperationException: There was an invalid operation!
   at MyApp.MyClass.MyExceptionMethod()
   at MyApp.MyClass.CallingMethod(System.String)
   at MyApp.MyClass.Main(System.String[])
```

### Sample Request

```http
POST /exceptions HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
Accept: text/plain
{
    "Include": [
        {
            "methodName": "MyExceptionMethod1"
        },
        {
            "methodName": "MyExceptionMethod2"
        }
    ]
}
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: text/plain

First chance exception at 2023-08-08T14:50:34.1039177Z
System.InvalidOperationException: There was an invalid operation!
   at MyApp.MyClass.MyExceptionMethod1()
   at MyApp.MyClass.CallingMethod(System.String)
   at MyApp.MyClass.Main(System.String[])

First chance exception at 2023-08-08T14:50:34.1039177Z
System.DivideByZeroException: You tried to divide by zero!
   at MyApp.MyClass.MyExceptionMethod2()
   at MyApp.MyClass.CallingMethod(System.String)
   at MyApp.MyClass.Main(System.String[])
```


### Sample Request

```http
POST /exceptions HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
Accept: text/plain
{
    "Include": [
        {
            "methodName": "MyExceptionMethod",
            "typeName": "MyApp.MyClass"
            "moduleName": "MyApp.dll"
            "exceptionType": "System.InvalidOperationException"
        }
    ]
}
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: text/plain

First chance exception at 2023-08-08T14:50:34.1039177Z
System.InvalidOperationException: There was an invalid operation!
   at MyApp.MyClass.MyExceptionMethod()
   at MyApp.MyClass.CallingMethod(System.String)
   at MyApp.MyClass.Main(System.String[])
```

### Sample Request

```http
POST /exceptions HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
Accept: application/x-ndjson
{
    "Include": [
        {
            "typeName": "MyClass"
        }
    ],
    "Exclude": [
        {
            "methodName": "MyExceptionMethod"
        }
    ],
}
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: application/x-ndjson

{"id":4,"timestamp":"2023-08-08T15:42:05.4014435Z","typeName":"System.DivideByZeroException","moduleName":"System.Private.CoreLib.dll","message":"Something was divided by zero!","stack":{"threadId":30448,"threadName":null,"innerExceptions":[],"frames":[{"methodName":"MyExceptionMethod2","parameterTypes":[],"typeName":"MyApp.MyClass","moduleName":"MyApp.dll"},{"methodName":"Main","parameterTypes":["System.String[]"],"typeName":"MyApp.MyClass","moduleName":"MyApp.dll"}]}}
{"id":6,"timestamp":"2023-08-08T15:42:06.411379Z","typeName":"System.Exception","moduleName":"System.Private.CoreLib.dll","message":"There was an exception!","stack":{"threadId":30448,"threadName":null,"innerExceptions":[],"frames":[{"methodName":"MyExceptionMethod3","parameterTypes":[],"typeName":"MyApp.MyClass","moduleName":"MyApp.dll"},{"methodName":"MyExceptionMethod4","parameterTypes":[],"typeName":"MyApp.MyClass","moduleName":"MyApp.dll"},{"methodName":"Main","parameterTypes":["System.String[]"],"typeName":"MyApp.MyClass","moduleName":"MyApp.dll"}]}}
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET 6+ |
| Linux | .NET 6+ |
| MacOS | .NET 6+ |

---

## File: documentation/api/gcdump.md

# GC Dump - Get

Captures a GC dump of a specified process. These dumps are useful for several scenarios:

- comparing the number of objects on the heap at several points in time
- analyzing roots of objects (answering questions like, "what still has a reference to this type?")
- collecting general statistics about the counts of objects on the heap.

> **WARNING:** To walk the GC heap, this route triggers a generation 2 (full) garbage collection, which can suspend the runtime for a long time, especially when the GC heap is large. Don't use this route in performance-sensitive environments when the GC heap is large.

## HTTP Route

```http
GET /gcdump?pid={pid}&uid={uid}&name={name}&egressProvider={egressProvider}&tags={tags} HTTP/1.1
```

> [!NOTE]
> Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.

## 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.

## URI Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pid` | query | false | int | The ID of the process. |
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
| `name` | query | false | string | The name of the process. |
| `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected GC dump. When not specified, the GC dump is written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
| `tags` | query | false | string | (7.1+) A comma-separated list of user-readable identifiers for the operation. |

See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.

If none of `pid`, `uid`, or `name` are specified, a GC dump of the [default process](defaultprocess.md) will be captured. Attempting to capture a GC dump of the default process when the default process cannot be resolved will fail.

## 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 | stream | A GC dump of the process when no egress provider is specified. | `application/octet-stream` |
| 202 Accepted | | When an egress provider is specified, the artifact has begun being collected. | |
| 400 Bad Request | [ValidationProblemDetails](definitions.md#validationproblemdetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
| 429 Too Many Requests | | There are too many GC dump requests at this time. Try to request a GC dump at a later time. | `application/problem+json` |

> [!NOTE]
> **(7.1+)** Regardless if an egress provider is specified if the request was successful (response codes 200 or 202), the Location header contains the URI of the operation. This can be used to query the status of the operation or change its state.

## Examples

### Sample Request

```http
GET /gcdump?pid=21632 HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

or

```http
GET /gcdump?uid=cd4da319-fa9e-4987-ac4e-e57b2aac248b HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=
```

### Sample Response

The GC dump, chunk encoded, is returned as the response body.

```http
HTTP/1.1 200 OK
Content-Type: application/octet-stream
Transfer-Encoding: chunked
Location: localhost:52323/operations/67f07e40-5cca-4709-9062-26302c484f18
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET Core 3.1, .NET 5+ |
| Linux | .NET Core 3.1, .NET 5+ |
| MacOS | .NET Core 3.1, .NET 5+ |

## Additional Notes

### When to use `pid` vs `uid`

See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.

### View the collected `.gcdump` file

On Windows, `.gcdump` files can be viewed in [PerfView](https://github.com/microsoft/perfview) for analysis or in Visual Studio. Currently, there is no way of opening a `.gcdump` on non-Windows platforms.

You can collect multiple `.gcdump`s and open them simultaneously in Visual Studio to get a comparison experience.

Reports can be generated from `.gcdump` files using the [dotnet-gcdump](https://docs.microsoft.com/dotnet/core/diagnostics/dotnet-gcdump) tool.

---

## File: documentation/api/info.md

# Info - Get

Gets information about the `dotnet monitor` version, the runtime version, and the diagnostic port settings.

## HTTP Route

```http
GET /info HTTP/1.1
```

## Host Address

The default host address for these routes is `https://localhost:52323`.

## Authentication

Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.

## Responses

| Name | Type | Description | Content Type |
|---|---|---|---|
| 200 OK | | Information about `dotnet monitor` formatted as JSON.  | `application/json` |
| 400 Bad Request | [ValidationProblemDetails](definitions.md#validationproblemdetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |

## Examples

### Sample Request

```http
GET /info HTTP/1.1
Host: localhost:52323
```

### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
    "version": "6.0.0",
    "runtimeVersion": "6.0.0",
    "diagnosticPortMode": "Connect",
    "diagnosticPortName": null,
    "capabilities": [{"name":"exceptions","enabled":true},{"name":"parameters","enabled":true},{"name":"call_stacks","enabled":true},{"name":"metrics","enabled":true},{"name":"http_egress","enabled":true}]
}
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET Core 3.1, .NET 5+ |
| Linux | .NET Core 3.1, .NET 5+ |
| MacOS | .NET Core 3.1, .NET 5+ |

---

## File: documentation/api/livemetrics.md

# Live Metrics

| Operation | Description |
|---|---|
| [Live Metrics](livemetrics-get.md) | Captures metrics using the default metric providers. |
| [Live Custom Metrics](livemetrics-custom.md) | Captures metrics using custom metric providers. |

---

## File: documentation/api/livemetrics-custom.md

# Livemetrics - Get Custom

Captures metrics for a process, with the ability to specify custom metrics.

## HTTP Route

```http
POST /livemetrics?pid={pid}&uid={uid}&name={name}&durationSeconds={durationSeconds}&egressProvider={egressProvider}&tags={tags} HTTP/1.1
```

> [!NOTE]
> Process information (IDs, names, environment, etc) may change between invocations of these APIs. Processes may start or stop between API invocations, causing this information to change.

## 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.

## URI Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `pid` | query | false | int | The ID of the process. |
| `uid` | query | false | guid | A value that uniquely identifies a runtime instance within a process. |
| `name` | query | false | string | The name of the process. |
| `durationSeconds` | query | false | int | The duration of the metrics operation in seconds. Default is `30`. Min is `-1` (indefinite duration). Max is `2147483647`. |
| `egressProvider` | query | false | string | If specified, uses the named egress provider for egressing the collected metrics. When not specified, the metrics are written to the HTTP response stream. See [Egress Providers](../egress.md) for more details. |
| `tags` | query | false | string | (7.1+) A comma-separated list of user-readable identifiers for the operation. |

See [ProcessIdentifier](definitions.md#processidentifier) for more details about the `pid`, `uid`, and `name` parameters.

If none of `pid`, `uid`, or `name` are specified, artifacts for the [default process](defaultprocess.md) will be captured. Attempting to capture artifacts of the default process when the default process cannot be resolved will fail.

## Authentication

Authentication is enforced for this route. See [Authentication](./../authentication.md) for further information.

Allowed schemes:
- `Bearer`
- `Negotiate` (Windows only, running as unelevated)

## Request Body

A request body of type [EventMetricsConfiguration](definitions.md#eventmetricsconfiguration) is required.

The expected content type is `application/json`.

## Responses

| Name | Type | Description | Content Type |
|---|---|---|---|
| 200 OK | [Metric](./definitions.md#metric) | The metrics from the process formatted as json sequence. Each JSON object is a [metrics object](./definitions.md#metric)| `application/json-seq` |
| 202 Accepted | | When an egress provider is specified, the artifact has begun being collected. | |
| 400 Bad Request | [ValidationProblemDetails](definitions.md#validationproblemdetails) | An error occurred due to invalid input. The response body describes the specific problem(s). | `application/problem+json` |
| 401 Unauthorized | | Authentication is required to complete the request. See [Authentication](./../authentication.md) for further information. | |
| 429 Too Many Requests | | There are too many requests at this time. Try to request metrics at a later time. | `application/problem+json` |

> [!NOTE]
> **(7.1+)** Regardless if an egress provider is specified if the request was successful (response codes 200 or 202), the Location header contains the URI of the operation. This can be used to query the status of the operation or change its state.

## Examples

### EventCounter

#### Sample Request

```http
POST /livemetrics?pid=21632&durationSeconds=60 HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=

{
    "includeDefaultProviders": false,
    "providers": [
        {
            "providerName": "CustomProvider",
            "counterNames": [
                "counter1",
                "counter2"
            ]
        }
    ]
}
```

#### Sample Response

```http
HTTP/1.1 200 OK
Content-Type: application/json-seq
Location: localhost:52323/operations/67f07e40-5cca-4709-9062-26302c484f18

{
    "timestamp": "2021-08-31T16:58:39.7514031+00:00",
    "provider": "CustomProvider",
    "name": "counter1",
    "displayName": "Counter 1",
    "unit": "B",
    "counterType": "Metric",
    "value": 3,
    "metadata": {
        "MyKey 1": "MyValue 1",
        "MyKey 2": "MyValue 2"
    }
}
{
    "timestamp": "2021-08-31T16:58:39.7515128+00:00",
    "provider": "CustomProvider",
    "name": "counter2",
    "displayName": "Counter 2",
    "unit": "MB",
    "counterType": "Metric",
    "value": 126,
    "metadata": {}
}
```

### System.Diagnostics.Metrics (8.0+)

#### Sample Request

```http
GET /livemetrics?pid=21632&durationSeconds=60 HTTP/1.1
Host: localhost:52323
Authorization: Bearer fffffffffffffffffffffffffffffffffffffffffff=

{
    "includeDefaultProviders": false,
    "meters": [
        {
            "meterName": "CustomMeter",
            "instrumentNames": [
                "myHistogram"
            ]
        }
    ]
}
```

#### Sample Histogram Response

```http
HTTP/1.1 200 OK
Content-Type: application/json-seq
Location: localhost:52323/operations/67f07e40-5cca-4709-9062-26302c484f18

{
    "timestamp": "2021-08-31T16:58:39.7514031+00:00",
    "provider": "CustomMeter",
    "name": "myHistogram",
    "displayName": "myHistogram",
    "unit": null,
    "counterType": "Metric",
    "tags": "Percentile=50",
    "value": 2292
}
{
    "timestamp": "2021-08-31T16:58:39.7514031+00:00",
    "provider": "CustomMeter",
    "name": "myHistogram",
    "displayName": "myHistogram",
    "unit": null,
    "counterType": "Metric",
    "tags": "Percentile=95",
    "value": 4616
}
{
    "timestamp": "2021-08-31T16:58:39.7514031+00:00",
    "provider": "CustomMeter",
    "name": "myHistogram",
    "displayName": "myHistogram",
    "unit": null,
    "counterType": "Metric",
    "tags": "Percentile=99",
    "value": 4960
}
```

## Supported Runtimes

| Operating System | Runtime Version |
|---|---|
| Windows | .NET Core 3.1, .NET 5+ |
| Linux | .NET Core 3.1, .NET 5+ |
| MacOS | .NET Core 3.1, .NET 5+ |

## Additional Notes

### When to use `pid` vs `uid`

See [Process ID `pid` vs Unique ID `uid`](pidvsuid.md) for clarification on when it is best to use either parameter.