dotnet-monitor Documentation

This repository contains the source code for .NET Monitor - a tool that allows you to gather diagnostic data from running applications using HTTP endpoints

726 stars C# C# 74 files · ~134,475 tokens
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy dotnet-monitor on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name dotnet-monitor -p 8080:8080 --restart always mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled
Configured Services & Ports
⚙️ app
image: mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled
🔌 Ports: 8080:8080
⚙️ monitor
image: mcr.microsoft.com/dotnet/monitor:8
🔌 Ports: 52323:52323, 52325:52325
docker-compose.yml
yaml (docker-compose.yml) 
# Tell us about your experience using dotnet monitor: https://aka.ms/dotnet-monitor-survey
services:
  app:
    image: mcr.microsoft.com/dotnet/samples:aspnetapp-chiseled
    ports:
      - "8080:8080"
    environment:
      - DOTNET_DiagnosticPorts=/diag/dotnet-monitor.sock
    volumes:
      - diagvol:/diag
    deploy:
      resources:
        limits:
          cpus: '0.250'
          memory: 512M

  monitor:
    image: mcr.microsoft.com/dotnet/monitor:8
    # DO NOT use the --no-auth argument for deployments in production; this argument is used for demonstration
    # purposes only in this example. Please continue reading after this example for further details.
    command: ["collect", "--no-auth"]
    ports:
      - "52323:52323"
      - "52325:52325"
    environment:
      - DOTNETMONITOR_DiagnosticPort__ConnectionMode=Listen
      - DOTNETMONITOR_Storage__DefaultSharedPath=/diag
      # ALWAYS use the HTTPS form of the URL for deployments in production; the removal of HTTPS is done for
      # demonstration purposes only in this example. Please continue reading after this example for further details.
      - DOTNETMONITOR_Urls=http://+:52323
      # The metrics URL is set in the CMD instruction of the image by default. However, this deployment overrides that with the args setting; manually set the URL to the same value using configuration.
      - DOTNETMONITOR_Metrics__Endpoints=http://+:52325
      # The image will output logging in a json format by default, which is great for ingestion by tools such as Azure Monitor Log Analytics.
      # Switch the logging format to simple for this sample for easier reading.
      - Logging__Console__FormatterName=simple
    volumes:
      - diagvol:/diag
    deploy:
      resources:
        reservations:
          cpus: '0.050'
          memory: 50M
        limits:
          cpus: '0.250'
          memory: 256M

volumes:
  diagvol:
    driver_opts:
      type: tmpfs
      device: tmpfs

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 Get the detailed state of the specified collection rule for all processes or for the specified process.
List Collection Rules 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 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 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 for further information.

Allowed schemes:

  • Bearer
  • Negotiate (Windows only, running as unelevated)

Responses

Name Type Description Content Type
200 OK CollectionRuleDetailedDescription The detailed information about the current state of the specified collection rule. application/json
400 Bad Request 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 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 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 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 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 for further information.

Allowed schemes:

  • Bearer
  • Negotiate (Windows only, running as unelevated)

Responses

Name Type Description Content Type
200 OK map (of CollectionRuleDescription) The basic information about the current state of the configured collection rules. application/json
400 Bad Request 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 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 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 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[] 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.
PlainText Stacks are formatted in plain text.
Speedscope Stacks are formatted in speedscope. 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 and should be omitted from stack trace text.

CallStackResult

First Available: 8.0 Preview 7

Name Type Description
stacks 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 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 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.
activityIdFormat string The activity Id format. For more information see 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[] 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[] Array of methods to capture parameters for.
useDebuggerDisplayAttribute bool Determines if parameters should be formatted using their 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[] (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[] Array of counter providers for metrics to collect.
meters 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 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 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[] 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[] The list of exceptions to include in the filter - anything not listed in the filter will not be included in the results.
exclude 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 ExceptionInstances that are the inner exceptions of the current exception.
stack 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 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 documentation.

LogsConfiguration

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

Name Type Description
logLevel LogLevel The default log level at which logs are collected. Default is Warning.
filterSpecs map (of 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. 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 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 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. Not all operations support being stopped.
process 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 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. Not all operations support being stopped.
process 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. 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 or higher.
Metrics Tracks event 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 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 for more details.
tags query false string (7.1+) A comma-separated list of user-readable identifiers for the operation.

See 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 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 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 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 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 for further details.

Additional Notes

When to use `pid` vs `uid`

See Process ID pid vs Unique ID uid 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 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 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 for more details.
tags query false string (7.1+) A comma-separated list of user-readable identifiers for the operation.

See 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 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 for further information.

Allowed schemes:

  • Bearer
  • Negotiate (Windows only, running as unelevated)

Responses

Name Type Description Content Type
200 OK ExceptionInstance[] Newline-delimited JSON representation of first chance exceptions from the target process. application/x-ndjson
200 OK 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 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 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 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 for more details.
tags query false string (7.1+) A comma-separated list of user-readable identifiers for the operation.

See 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 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 for further information.

Allowed schemes:

  • Bearer
  • Negotiate (Windows only, running as unelevated)

Request Body

A request body of type ExceptionsConfiguration is required.

The expected content type is application/json.

Responses

Name Type Description Content Type
200 OK 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 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 for more details.
tags query false string (7.1+) A comma-separated list of user-readable identifiers for the operation.

See 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 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 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 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 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 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 for analysis or in Visual Studio. Currently, there is no way of opening a .gcdump on non-Windows platforms.

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

Reports can be generated from .gcdump files using the 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 for further information.

Responses

Name Type Description Content Type
200 OK Information about dotnet monitor formatted as JSON. application/json
400 Bad Request 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 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 Captures metrics using the default metric providers.
Live Custom Metrics 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 for more details.
tags query false string (7.1+) A comma-separated list of user-readable identifiers for the operation.

See 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 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 for further information.

Allowed schemes:

  • Bearer
  • Negotiate (Windows only, running as unelevated)

Request Body

A request body of type EventMetricsConfiguration is required.

The expected content type is application/json.

Responses

Name Type Description Content Type
200 OK Metric The metrics from the process formatted as json sequence. Each JSON object is a metrics object application/json-seq
202 Accepted When an egress provider is specified, the artifact has begun being collected.
400 Bad Request 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 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 for clarification on when it is best to use either parameter.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →