Note
Some features are experimental and are denoted as **[Experimental]**
in this document.
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. |
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. |
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. |
First Available: 8.0 Preview 7
Name | Type | Description |
---|---|---|
stacks |
CallStack[] | List of all managed stacks at the time of collection. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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 . |
{
"Providers": [{
"Name": "Microsoft-DotNETCore-SampleProfiler",
"EventLevel": "Informational"
},{
"Name": "Microsoft-Windows-DotNETRuntime",
"EventLevel": "Informational",
"Keywords": "0x14C14FCCBD"
}],
"BufferSizeInMB": 1024
}
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"). |
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. |
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. |
First Available: 8.0 RC 1
Enumeration that describes the format to use when outputting exceptions.
Name |
---|
JsonSequence |
NewlineDelimitedJson |
PlainText |
Enumeration that describes additional execution modes supported by the extension; the ability to execute is assumed.
Name |
---|
Validate |
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. |
If an application logged the following message:
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:
{
"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."
}
}
Enumeration that describes the format to use when outputting logs.
Name |
---|
JsonSequence |
NewlineDelimitedJson |
PlainText |
Enumeration that defines logging severity levels.
See LogLevel documentation.
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 . |
The following configuration will collect logs for the Microsoft.AspNetCore.Hosting category at the Information level or higher.
{
"filterSpecs": {
"Microsoft.AspNetCore.Hosting": "Information"
},
"useAppFilters": false
}
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. |
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. |
Name | Type | Description |
---|---|---|
code |
string | Error code representing the failure. |
message |
string | Detailed error message. |
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. |
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. |
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. |
{
"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"
]
}
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. |
{
"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"
]
}
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.
{
"pid": 21632,
"uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b"
}
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 . |
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).
{
"pid": 21632,
"uid": "cd4da319-fa9e-4987-ac4e-e57b2aac248b",
"name": "dotnet",
"commandLine": "\"C:\\Program Files\\dotnet\\dotnet.exe\" ConsoleApp1.dll",
"operatingSystem": "Windows",
"processArchitecture": "x64"
}
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. |
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 . |
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. |
{
"title": "One or more validation errors occurred.",
"status": 400,
"errors": {
"Providers": [
"The Providers field is required."
]
}
}