Skip to content

Latest commit

 

History

History
1357 lines (1073 loc) · 52 KB

collection-rule-configuration.md

File metadata and controls

1357 lines (1073 loc) · 52 KB

Collection Rule Configuration

dotnet monitor can be configured to automatically collect diagnostic artifacts based on conditions within the discovered processes.

Collection rules are specified in configuration as a named item under the CollectionRules property at the root of the configuration. Each collection rule has four properties for describing the behavior of the rule:

Example

< The following is a collection rule that collects a 1 minute CPU trace and egresses it to a provider named "TmpDir" after it has detected high CPU usage for 10 seconds. The rule only applies to processes named "dotnet" and only collects at most 2 traces per 1 hour sliding time window.

JSON
{
    "CollectionRules": {
        "HighCpuRule": {
            "Filters": [{
                "Key": "ProcessName",
                "Value": "dotnet",
                "MatchType": "Exact"
            }],
            "Trigger": {
                "Type": "EventCounter",
                "Settings": {
                    "ProviderName": "System.Runtime",
                    "CounterName": "cpu-usage",
                    "GreaterThan": 70,
                    "SlidingWindowDuration": "00:00:10"
                }
            },
            "Actions": [{
                "Type": "CollectTrace",
                "Settings": {
                    "Profile": "Cpu",
                    "Duration": "00:01:00",
                    "Egress": "TmpDir"
                }
            }],
            "Limits": {
                "ActionCount": 2,
                "ActionCountSlidingWindowDuration": "1:00:00"
            }
        }
    }
}
Kubernetes ConfigMap
CollectionRules__HighCpuRule__Filters__0__Key: "ProcessName"
CollectionRules__HighCpuRule__Filters__0__Value: "dotnet"
CollectionRules__HighCpuRule__Filters__0__MatchType: "Exact"
CollectionRules__HighCpuRule__Trigger__Type: "EventCounter"
CollectionRules__HighCpuRule__Trigger__Settings__ProviderName: "System.Runtime"
CollectionRules__HighCpuRule__Trigger__Settings__CounterName: "cpu-usage"
CollectionRules__HighCpuRule__Trigger__Settings__GreaterThan: "70"
CollectionRules__HighCpuRule__Trigger__Settings__SlidingWindowDuration: "00:00:10"
CollectionRules__HighCpuRule__Actions__0__Type: "CollectTrace"
CollectionRules__HighCpuRule__Actions__0__Settings__Profile: "Cpu"
CollectionRules__HighCpuRule__Actions__0__Settings__Duration: "00:01:00"
CollectionRules__HighCpuRule__Actions__0__Settings__Egress: "TmpDir"
CollectionRules__HighCpuRule__Limits__ActionCount: "2"
CollectionRules__HighCpuRule__Limits__ActionCountSlidingWindowDuration: "1:00:00"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__HighCpuRule__Filters__0__Key
  value: "ProcessName"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Filters__0__Value
  value: "dotnet"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Filters__0__MatchType
  value: "Exact"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Trigger__Type
  value: "EventCounter"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Trigger__Settings__ProviderName
  value: "System.Runtime"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Trigger__Settings__CounterName
  value: "cpu-usage"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Trigger__Settings__GreaterThan
  value: "70"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Trigger__Settings__SlidingWindowDuration
  value: "00:00:10"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Actions__0__Type
  value: "CollectTrace"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Actions__0__Settings__Profile
  value: "Cpu"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Actions__0__Settings__Duration
  value: "00:01:00"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Actions__0__Settings__Egress
  value: "TmpDir"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Limits__ActionCount
  value: "2"
- name: DotnetMonitor_CollectionRules__HighCpuRule__Limits__ActionCountSlidingWindowDuration
  value: "1:00:00"

Filters

Each collection rule can specify a set of process filters to select which processes the rule should be applied. The filter criteria are the same as those used for the default process configuration.

Example

The following example shows the Filters portion of a collection rule that has the rule only apply to processes named dotnet and whose command line contains myapp.dll.

JSON
{
    "Filters": [{
        "Key": "ProcessName",
        "Value": "dotnet",
        "MatchType": "Exact"
    },{
        "CommandLine": "myapp.dll",
        "MatchType": "Contains"
    }]
}
Kubernetes ConfigMap
CollectionRules__RuleName__Filters__0__Key: "ProcessName"
CollectionRules__RuleName__Filters__0__Value: "dotnet"
CollectionRules__RuleName__Filters__0__MatchType: "Exact"
CollectionRules__RuleName__Filters__1__CommandLine: "myapp.dll"
CollectionRules__RuleName__Filters__1__MatchType: "Contains"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Filters__0__Key
  value: "ProcessName"
- name: DotnetMonitor_CollectionRules__RuleName__Filters__0__Value
  value: "dotnet"
- name: DotnetMonitor_CollectionRules__RuleName__Filters__0__MatchType
  value: "Exact"
- name: DotnetMonitor_CollectionRules__RuleName__Filters__1__CommandLine
  value: "myapp.dll"
- name: DotnetMonitor_CollectionRules__RuleName__Filters__1__MatchType
  value: "Contains"

Triggers

A trigger will monitor for a specific condition in the target application and raise a notification when that condition has been observed.

AspNetRequestCount Trigger

A trigger that has its condition satisfied when the number of HTTP requests is above the described threshold level for a sliding window of time. The request paths can be filtered according to the described patterns.

Properties

Name Type Required Description Default Value Min Value Max Value
RequestCount int true The threshold of the number of requests that start within the sliding window of time.
SlidingWindowDuration TimeSpan? false The sliding time window in which the number of requests are counted. "00:01:00" (one minute) "00:00:01" (one second) "1.00:00:00" (1 day)
IncludePaths string[] false The list of request path patterns to monitor. If not specified, all request paths are considered. If specified, only request paths matching one of the patterns in this list will be considered. Request paths matching a pattern in the ExcludePaths list will be ignored. null
ExcludePaths string[] false The list of request path patterns to ignore. Request paths matching a pattern in this list will be ignored. null

The IncludePaths and ExcludePaths support wildcards and globbing.

Example

Usage that is satisfied when request count is higher than 500 requests during a 1 minute period for all paths under the /api route:

JSON
{
  "RequestCount": 500,
  "SlidingWindowDuration": "00:01:00",
  "IncludePaths": [ "/api/**/*" ]
}
Kubernetes ConfigMap
CollectionRules__RuleName__Trigger__Settings__RequestCount: "500"
CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration: "00:01:00"
CollectionRules__RuleName__Trigger__Settings__IncludePaths__0: "/api/**/*"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__RequestCount
  value: "500"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration
  value: "00:01:00"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__IncludePaths__0
  value: "/api/**/*"

AspNetRequestDuration Trigger

A trigger that has its condition satisfied when the number of HTTP requests have response times longer than the threshold duration for a sliding window of time. Long running requests (ones that do not send a complete response within the threshold duration) are included in the count. The request paths can be filtered according to the described patterns.

Properties

Name Type Required Description Default Value Min Value Max Value
RequestCount int true The threshold of the number of slow requests that start within the sliding window of time.
RequestDuration TimeSpan? false The threshold of the amount of time in which a request is considered to be slow. "00:00:05" (5 seconds) "00:00:00" (zero seconds) "01:00:00" (1 hour)
SlidingWindowDuration TimeSpan? false The sliding time window in which the the number of slow requests are counted. "00:01:00" (one minute) "00:00:01" (one second) "1.00:00:00" (1 day)
IncludePaths string[] false The list of request path patterns to monitor. If not specified, all request paths are considered. If specified, only request paths matching one of the patterns in this list will be considered. Request paths matching a pattern in the ExcludePaths list will be ignored. null
ExcludePaths string[] false The list of request path patterns to ignore. Request paths matching a pattern in this list will be ignored. null

The IncludePaths and ExcludePaths support wildcards and globbing.

Example

Usage that is satisfied when 10 requests take longer than 3 seconds during a 1 minute period for all paths under the /api route:

JSON
{
  "RequestCount": 10,
  "RequestDuration": "00:00:03",
  "SlidingWindowDuration": "00:01:00",
  "IncludePaths": [ "/api/**/*" ]
}
Kubernetes ConfigMap
CollectionRules__RuleName__Trigger__Settings__RequestCount: "10"
CollectionRules__RuleName__Trigger__Settings__RequestDuration: "00:00:03"
CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration: "00:01:00"
CollectionRules__RuleName__Trigger__Settings__IncludePaths__0: "/api/**/*"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__RequestCount
  value: "10"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__RequestDuration
  value: "00:00:03"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration
  value: "00:01:00"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__IncludePaths__0
  value: "/api/**/*"

AspNetResponseStatus Trigger

A trigger that has its condition satisfied when the number of HTTP responses that have status codes matching the pattern list is above the specified threshold for a sliding window of time. The request paths can be filtered according to the described patterns.

Properties

Name Type Required Description Default Value Min Value Max Value
StatusCodes string[] true The list of HTTP response status codes to monitor. Each item of the list can be a single code or a range of codes (e.g. "400-499").
RequestCount int true The threshold number of responses with matching status codes.
SlidingWindowDuration TimeSpan? false The sliding time window in which the number of responses with matching status codes must occur. "00:01:00" (one minute) "00:00:01" (one second) "1.00:00:00" (1 day)
IncludePaths string[] false The list of request path patterns to monitor. If not specified, all request paths are considered. If specified, only request paths matching one of the patterns in this list will be considered. Request paths matching a pattern in the ExcludePaths list will be ignored. null
ExcludePaths string[] false The list of request path patterns to ignore. Request paths matching a pattern in this list will be ignored. null

The IncludePaths and ExcludePaths support wildcards and globbing.

Example

Usage that is satisfied when 10 requests respond with a 5XX status code during a 1 minute period for all paths under the /api route:

JSON
{
  "StatusCodes": [ "500-599" ],
  "RequestCount": 10,
  "SlidingWindowDuration": "00:01:00",
  "IncludePaths": [ "/api/**/*" ]
}
Kubernetes ConfigMap
CollectionRules__RuleName__Trigger__Settings__StatusCodes__0: "500-599"
CollectionRules__RuleName__Trigger__Settings__RequestCount: "10"
CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration: "00:01:00"
CollectionRules__RuleName__Trigger__Settings__IncludePaths__0: "/api/**/*"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__StatusCodes__0
  value: "500-599"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__RequestCount
  value: "10"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration
  value: "00:01:00"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__IncludePaths__0
  value: "/api/**/*"

EventCounter Trigger

A trigger that has its condition satisfied when the value of a counter falls above, below, or between the described threshold values for a duration of time.

See Well-known Counters in .NET for a list of known available counters. Custom counters from custom event sources are supported as well.

Properties

Name Type Required Description Default Value Min Value Max Value
ProviderName string true The name of the event source that provides the counter information.
CounterName string true The name of the counter to monitor.
GreaterThan double? false The threshold level the counter must maintain (or higher) for the specified duration. Either GreaterThan or LessThan (or both) must be specified. null
LessThan double? false The threshold level the counter must maintain (or lower) for the specified duration. Either GreaterThan or LessThan (or both) must be specified. null
SlidingWindowDuration false TimeSpan? The sliding time window in which the counter must maintain its value as specified by the threshold levels in GreaterThan and/or LessThan. "00:01:00" (one minute) "00:00:01" (one second) "1.00:00:00" (1 day)

Example

Usage that is satisfied when the CPU usage of the application is higher than 70% for a 10 second window.

JSON
{
  "ProviderName": "System.Runtime",
  "CounterName": "cpu-usage",
  "GreaterThan": 70,
  "SlidingWindowDuration": "00:00:10"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Trigger__Settings__ProviderName: "System.Runtime"
CollectionRules__RuleName__Trigger__Settings__CounterName: "cpu-usage"
CollectionRules__RuleName__Trigger__Settings__GreaterThan: "70"
CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration: "00:00:10"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__ProviderName
  value: "System.Runtime"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__CounterName
  value: "cpu-usage"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__GreaterThan
  value: "70"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration
  value: "00:00:10"

EventMeter Trigger (8.0+)

A trigger that has its condition satisfied when the value of an instrument falls above, below, or between the described threshold value for a duration of time. Supported instruments include Gauges, Counters, and Histograms.

Properties

Name Type Required Description Default Value Min Value Max Value
MeterName string true The name of the meter that provides the instrument information.
InstrumentName string true The name of the instrument to monitor.
GreaterThan double? false The threshold level the instrument must maintain (or higher) for the specified duration. Either GreaterThan or LessThan (or both) must be specified for non-histogram instruments. null
LessThan double? false The threshold level the instrument must maintain (or lower) for the specified duration. Either GreaterThan or LessThan (or both) must be specified for non-histogram instruments. null
SlidingWindowDuration TimeSpan? false The sliding time window in which the instrument must maintain its value as specified by the threshold levels in GreaterThan and/or LessThan. "00:01:00" (one minute) "00:00:01" (one second) "1.00:00:00" (1 day)
HistogramPercentile int? false The histogram percentile should be one of the instrument's published percentiles (by default: 50, 95, and 99) and is only specified when the instrument is a histogram. The provided percentile's value will be used to compare against GreaterThan and/or LessThan. 0 100

Example

Usage that is satisfied when the target application's custom gauge is greater than 20 for a 10 second window.

JSON
{
  "MeterName": "MyMeterName",
  "InstrumentName": "MyGaugeName",
  "GreaterThan": 20,
  "SlidingWindowDuration": "00:00:10"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Trigger__Settings__MeterName: "MyMeterName"
CollectionRules__RuleName__Trigger__Settings__InstrumentName: "MyGaugeName"
CollectionRules__RuleName__Trigger__Settings__GreaterThan: "20"
CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration: "00:00:10"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__MeterName
  value: "MyMeterName"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__InstrumentName
  value: "MyGaugeName"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__GreaterThan
  value: "20"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration
  value: "00:00:10"

Example

Usage that is satisfied when the target application's custom histogram for a 10 second window has its 50th Percentile greater than 200:

JSON
{
  "MeterName": "MyMeterName",
  "InstrumentName": "MyHistogramName",
  "GreaterThan": 200,
  "HistogramPercentile": 50,
  "SlidingWindowDuration": "00:00:10"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Trigger__Settings__MeterName: "MyMeterName"
CollectionRules__RuleName__Trigger__Settings__InstrumentName: "MyHistogramName"
CollectionRules__RuleName__Trigger__Settings__GreaterThan: "200"
CollectionRules__RuleName__Trigger__Settings__HistogramPercentile: "50"
CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration: "00:00:10"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__MeterName
  value: "MyMeterName"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__InstrumentName
  value: "MyGaugeName"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__GreaterThan
  value: "200"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__HistogramPercentile
  value: "50"
- name: DotnetMonitor_CollectionRules__RuleName__Trigger__Settings__SlidingWindowDuration
  value: "00:00:10"

Built-In Default Triggers

These trigger shortcuts simplify configuration for several common EventCounter providers.

ASP.NET Request Path Wildcards and Globbing

The IncludePaths and ExcludePaths properties of the ASP.NET triggers allow for wildcards and globbing so that every included or excluded path does not necessarily need to be explicitly specified. For these triggers, a match with an ExcludePaths pattern will supersede a match with an IncludePaths pattern.

The globstar **/ will match zero or more path segments including the forward slash / character at the end of the segment.

The wildcard * will match zero or more non-forward-slash / characters.

Examples

Pattern Matches Non-Matches
**/* All paths No exclusions
/images/**/* /images/logo.png, /images/products/1.png /index/header.png
**/*.js /script.js, /path/script.js, /path/sub/script.js /script.js/page.html
**/sub/*.html /path/sub/page.html, /sub/page.html /sub/script.js, /path/doc.txt

Actions

Actions allow executing an operation or an external executable in response to a trigger condition being satisfied.

CollectDump Action

An action that collects a dump of the process that the collection rule is targeting.

Properties

Name Type Required Description Default Value
Type DumpType false The type of dump to collect WithHeap
Egress string true The named egress provider for egressing the collected dump.

Outputs

Name Description
EgressPath The path of the file that was egressed using the specified egress provider.

Example

Usage that collects a full dump and egresses it to a provider named "AzureBlobDumps".

JSON
{
  "Type": "Full",
  "Egress": "AzureBlobDumps"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Type: "Full"
CollectionRules__RuleName__Actions__0__Settings__Egress: "AzureBlobDumps"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Type
  value: "Full"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "AzureBlobDumps"

CollectExceptions Action

First Available: 8.0 RC 1

An action that collects exceptions from the process that the collection rule is targeting.

Properties

Name Type Required Description Default Value
Egress string true The named egress provider for egressing the collected dump.
Format ExceptionFormat? false The format of the exception entries. PlainText
Filters ExceptionsConfiguration? false Determines which exceptions should be included/excluded in the result - note that this does not alter which exceptions are collected.

Outputs

Name Description
EgressPath The path of the file that was egressed using the specified egress provider.

Example

Usage that collects exceptions as newline-delimited JSON and egresses it to a provider named "AzureBlobExceptions".

JSON
{
  "Egress": "AzureBlobExceptions",
  "Format": "NewlineDelimitedJson"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Egress: "AzureBlobExceptions"
CollectionRules__RuleName__Actions__0__Settings__Format: "NewlineDelimitedJson"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "AzureBlobExceptions"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Format
  value: "NewlineDelimitedJson"

CollectGCDump Action

An action that collects a gcdump of the process that the collection rule is targeting.

Properties

Name Type Required Description Default Value
Egress string true The named egress provider for egressing the collected gcdump.

Outputs

Name Description
EgressPath The path of the file that was egressed using the specified egress provider.

Example

Usage that collects a gcdump and egresses it to a provider named "AzureBlobGCDumps".

JSON
{
  "Egress": "AzureBlobGCDumps"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Egress: "AzureBlobGCDumps"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "AzureBlobGCDumps"

CollectTrace Action

An action that collects a trace of the process that the collection rule is targeting.

Properties

Name Type Required Description Default Value Min Value Max Value
Profile TraceProfile? false The name of the profile(s) used to collect events. See TraceProfile for details on the list of event providers, levels, and keywords each profile represents. Multiple profiles may be specified by separating them with commas. Either Profile or Providers must be specified, but not both. null
Providers EventProvider[] false List of event providers from which to capture events. Either Profile or Providers must be specified, but not both. null
RequestRundown bool false 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. Only applies when Providers is specified. true
BufferSizeMegabytes int false 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. Only applies when Providers is specified. 256 1 1024
Duration TimeSpan? false The duration of the trace operation. "00:00:30" (30 seconds) "00:00:01" (1 second) "1.00:00:00" (1 day)
Egress string true The named egress provider for egressing the collected trace.
StoppingEvent TraceEventFilter? false The event to watch for while collecting the trace, and once either the event is hit or the Duration is reached the trace will be stopped. This can only be specified if Providers is set. null

Outputs

Name Description
EgressPath The path of the file that was egressed using the specified egress provider.

Example

Usage that collects a CPU trace for 30 seconds and egresses it to a provider named "TmpDir".

JSON
{
  "Profile": "Cpu",
  "Egress": "TmpDir"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Profile: "Cpu"
CollectionRules__RuleName__Actions__0__Settings__Egress: "TmpDir"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Profile
  value: "Cpu"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "TmpDir"

CollectLiveMetrics Action

An action that collects live metrics for the process that the collection rule is targeting.

Note

(8.0+) If none of IncludeDefaultProviders, Provider, or Meters are specified, then the metrics configuration is used as the collection specification.

Properties

Name Type Required Description Default Value Min Value Max Value
IncludeDefaultProviders bool false Determines if the default counter providers should be used. true
Providers EventMetricsProvider[] false The array of providers for metrics to collect.
Meters EventMetricsMeter[] false (7.1+) The array of meters for metrics to collect.
Duration TimeSpan? false The duration of the live metrics operation. "00:00:30" (30 seconds) "00:00:01" (1 second) "1.00:00:00" (1 day)
Egress string true The named egress provider for egressing the collected live metrics.

Outputs

Name Description
EgressPath The path of the file that was egressed using the specified egress provider.

Example

Usage that collects live metrics with the default providers for 30 seconds and egresses it to a provider named "TmpDir".

JSON
{
  "Egress": "TmpDir"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Egress: "TmpDir"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "TmpDir"

Example

Usage that collects live metrics for the cpu-usage counter on System.Runtime for 20 seconds and egresses it to a provider named "TmpDir".

JSON
{
  "UseDefaultProviders": false,
  "Providers": [
    {
      "ProviderName": "System.Runtime",
      "CounterNames": [ "cpu-usage" ]
    }
  ],
  "Egress": "TmpDir"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__UseDefaultProviders: "false"
CollectionRules__RuleName__Actions__0__Settings__Providers__0__ProviderName: "System.Runtime"
CollectionRules__RuleName__Actions__0__Settings__Providers__0__CounterNames__0: "cpu-usage"
CollectionRules__RuleName__Actions__0__Settings__Egress: "TmpDir"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__UseDefaultProviders
  value: "false"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Providers__0__ProviderName
  value: "System.Runtime"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Providers__0__CounterNames__0
  value: "cpu-usage"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "TmpDir"

CollectLogs Action

An action that collects logs for the process that the collection rule is targeting.

Properties

Name Type Required Description Default Value Min Value Max Value
DefaultLevel LogLevel? false The default log level at which logs are collected for entries in the FilterSpecs that do not have a specified LogLevel value. LogLevel.Warning
FilterSpecs Dictionary<string, LogLevel?> false A custom mapping of logger categories to log levels that describes at what level a log statement that matches one of the given categories should be captured. null
UseAppFilters bool false Specifies whether to capture log statements at the levels as specified in the application-defined filters. true
Format LogFormat? false The format of the logs artifact. PlainText
Duration TimeSpan? false The duration of the logs operation. "00:00:30" (30 seconds) "00:00:01" (1 second) "1.00:00:00" (1 day)
Egress string true The named egress provider for egressing the collected logs.

Outputs

Name Description
EgressPath The path of the file that was egressed using the specified egress provider.

Example

Usage that collects logs at the Information level for 30 seconds and egresses it to a provider named "TmpDir".

JSON
{
  "DefaultLevel": "Information",
  "UseAppFilters": false,
  "Egress": "TmpDir"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__DefaultLevel: "Information"
CollectionRules__RuleName__Actions__0__Settings__UseAppFilters: "false"
CollectionRules__RuleName__Actions__0__Settings__Egress: "TmpDir"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__DefaultLevel
  value: "Information"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__UseAppFilters
  value: "false"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "TmpDir"

Execute Action

An action that executes an executable found in the file system. Non-zero exit code will fail the action.

Properties

Name Type Required Description Default Value
Path string true The path to the executable.
Arguments string false The arguments to pass to the executable. null
IgnoreExitCode bool? false Ignores checking that the exit code is zero. false

Outputs

Name Description
ExitCode The exit code of the process.

Example

Usage that executes a .NET executable named myapp.dll using dotnet.

JSON
{
  "Path": "C:\\Program Files\\dotnet\\dotnet.exe",
  "Arguments": "C:\\Program Files\\MyApp\\myapp.dll"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Path: "C:\\Program Files\\dotnet\\dotnet.exe"
CollectionRules__RuleName__Actions__0__Settings__Arguments: "C:\\Program Files\\MyApp\\myapp.dll"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Path
  value: "C:\\Program Files\\dotnet\\dotnet.exe"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Arguments
  value: "C:\\Program Files\\MyApp\\myapp.dll"

CollectStacks Action

First Available: 8.0 Preview 7

Collect call stacks from the target process.

Note

This feature is not enabled by default and requires configuration to be enabled. The in-process features must be enabled since the call stacks feature uses shared libraries loaded into the target application for collecting the call stack information.

Properties

Name Type Required Description Default Value
Format CallStackFormat false The format of the collected call stack. Json
Egress string true The named egress provider for egressing the collected stacks.

LoadProfiler Action

An action that loads an ICorProfilerCallback implementation into a target process as a startup profiler. This action must be used in a collection rule with a Startup trigger.

Properties

Name Type Required Description Default Value
Path string true The path of the profiler library to be loaded. This is typically the same value that would be set as the CORECLR_PROFILER_PATH environment variable.
Clsid Guid true The class identifier (or CLSID, typically a GUID) of the ICorProfilerCallback implementation. This is typically the same value that would be set as the CORECLR_PROFILER environment variable.

Outputs

No outputs

Example

Usage that loads one of the sample profilers from dotnet/runtime: src/tests/profiler/native/gcallocateprofiler/gcallocateprofiler.cpp.

JSON
{
  "Path": "Profilers\\Profiler.dll",
  "Clsid": "55b9554d-6115-45a2-be1e-c80f7fa35369"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Path: "Profilers\\Profiler.dll"
CollectionRules__RuleName__Actions__0__Settings__Clsid: "55b9554d-6115-45a2-be1e-c80f7fa35369"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Path
  value: "Profilers\\Profiler.dll"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Clsid
  value: "55b9554d-6115-45a2-be1e-c80f7fa35369"

SetEnvironmentVariable Action

An action that sets an environment variable value in the target process. This action should be used in a collection rule with a Startup trigger.

Properties

Name Type Required Description Default Value
Name string true The name of the environment variable to set.
Value string false The value of the environment variable to set. null

Outputs

No outputs

Example

Usage that sets a parameter to the profiler you loaded. In this case, your profiler might be looking for an account key defined in MyProfiler_AccountId which is used to communicate to some outside system.

JSON
{
  "Name": "MyProfiler_AccountId",
  "Value": "8fb138d2c44e4aea8545cc2df541ed4c"
}
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Settings__Name: "MyProfiler_AccountId"
CollectionRules__RuleName__Actions__0__Settings__Value: "8fb138d2c44e4aea8545cc2df541ed4c"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Name
  value: "MyProfiler_AccountId"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Value
  value: "8fb138d2c44e4aea8545cc2df541ed4c"

GetEnvironmentVariable Action

An action that gets an environment variable from the target process. Its value is set as the Value action output.

Properties

Name Type Required Description Default Value
Name string true The name of the environment variable to get.

Outputs

Name Description
Value The value of the environment variable in the target process.

Example

Usage that gets a token your app has access to and uses it to send a trace.

Note

The example below is of an entire action list to provide context, only the second json entry represents the GetEnvironmentVariable Action.

JSON
[{
    "Name": "A",
    "Type": "CollectTrace",
    "Settings": {
        "Profile": "Cpu",
        "Egress": "AzureBlob"
    }
},{
    "Name": "GetEnvAction",
    "Type": "GetEnvironmentVariable",
    "Settings": {
       "Name": "Azure_SASToken",
    }
},{
    "Name": "B",
    "Type": "Execute",
    "Settings": {
        "Path": "azcopy",
        "Arguments": "$(Actions.A.EgressPath) https://Contoso.blob.core.windows.net/MyTraces/AwesomeAppTrace.nettrace?$(Actions.GetEnvAction.Value)"
    }
}]
Kubernetes ConfigMap
CollectionRules__RuleName__Actions__0__Name: "A"
CollectionRules__RuleName__Actions__0__Type: "CollectTrace"
CollectionRules__RuleName__Actions__0__Settings__Profile: "Cpu"
CollectionRules__RuleName__Actions__0__Settings__Egress: "AzureBlob"
CollectionRules__RuleName__Actions__1__Name: "GetEnvAction"
CollectionRules__RuleName__Actions__1__Type: "GetEnvironmentVariable"
CollectionRules__RuleName__Actions__1__Settings__Name: "Azure_SASToken"
CollectionRules__RuleName__Actions__2__Name: "B"
CollectionRules__RuleName__Actions__2__Type: "Execute"
CollectionRules__RuleName__Actions__2__Settings__Path: "azcopy"
CollectionRules__RuleName__Actions__2__Settings__Arguments: "$(Actions.A.EgressPath) https://Contoso.blob.core.windows.net/MyTraces/AwesomeAppTrace.nettrace?$(Actions.GetEnvAction.Value)"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Name
  value: "A"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Type
  value: "CollectTrace"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Profile
  value: "Cpu"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__0__Settings__Egress
  value: "AzureBlob"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__1__Name
  value: "GetEnvAction"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__1__Type
  value: "GetEnvironmentVariable"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__1__Settings__Name
  value: "Azure_SASToken"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__2__Name
  value: "B"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__2__Type
  value: "Execute"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__2__Settings__Path
  value: "azcopy"
- name: DotnetMonitor_CollectionRules__RuleName__Actions__2__Settings__Arguments
  value: "$(Actions.A.EgressPath) https://Contoso.blob.core.windows.net/MyTraces/AwesomeAppTrace.nettrace?$(Actions.GetEnvAction.Value)"

Limits

Collection rules have limits that constrain the lifetime of the rule and how often its actions can be run before being throttled.

Name Type Required Description Default Value Min Value Max Value
ActionCount int false The number of times the action list may be executed before being throttled. 5
ActionCountSlidingWindowDuration TimeSpan? false 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. null "00:00:01" (1 second) "1.00:00:00" (1 day)
RuleDuration TimeSpan? false The amount of time 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. null "00:00:01" (1 second) "365.00:00:00" (1 year)

Example

The following example shows the Limits portion of a collection rule that has the rule only allow its actions to run 3 times within a 1 hour sliding time window.

JSON
{
    "Limits": {
        "ActionCount": 3,
        "ActionCountSlidingWindowDuration": "01:00:00"
    }
}
Kubernetes ConfigMap
CollectionRules__RuleName__Limits__ActionCount: "3"
CollectionRules__RuleName__Limits__ActionCountSlidingWindowDuration: "01:00:00"
Kubernetes Environment Variables
- name: DotnetMonitor_CollectionRules__RuleName__Limits__ActionCount
  value: "3"
- name: DotnetMonitor_CollectionRules__RuleName__Limits__ActionCountSlidingWindowDuration
  value: "01:00:00"

Collection Rule Defaults

Collection rule defaults are specified in configuration as a named item under the CollectionRuleDefaults property at the root of the configuration. Defaults can be used to limit the verbosity of configuration, allowing frequently used values for collection rules to be assigned as defaults. The following are the currently supported collection rule defaults:

Name Section Type Applies To
Egress Actions string CollectDump, CollectGCDump, CollectTrace, CollectLiveMetrics, CollectLogs
SlidingWindowDuration Triggers TimeSpan? AspNetRequestCount, AspNetRequestDuration, AspNetResponseStatus, EventCounter
RequestCount Triggers int AspNetRequestCount, AspNetRequestDuration
ResponseCount Triggers int AspNetResponseStatus
ActionCount Limits int Limits
ActionCountSlidingWindowDuration Limits TimeSpan? Limits
RuleDuration Limits TimeSpan? Limits

Example

The following example includes a default egress provider that corresponds to the FileSystem egress provider named artifacts. The first action, CollectDump, is able to omit the Settings section by using the default egress provider. The second action, CollectGCDump, is using an egress provider other than the default, and specifies that it will egress to an AzureBlobStorage provider named monitorBlob.

JSON
{
  "Egress": {
    "AzureBlobStorage": {
      "monitorBlob": {
        "accountUri": "https://exampleaccount.blob.core.windows.net",
        "containerName": "dotnet-monitor",
        "blobPrefix": "artifacts",
        "accountKeyName": "MonitorBlobAccountKey"
      }
    },
    "Properties": {
      "MonitorBlobAccountKey": "accountKey"
    },
    "FileSystem": {
      "artifacts": {
        "directoryPath": "/artifacts",
        "intermediateDirectoryPath": "/intermediateArtifacts"
      }
    }
  },
  "CollectionRuleDefaults": {
    "Actions": {
      "Egress": "artifacts"
    }
  },
  "CollectionRules": {
    "HighRequestCount": {
      "Trigger": {
        "Type": "AspNetRequestCount",
        "Settings": {
          "RequestCount": 10
        }
      },
      "Actions": [
        {
          "Type": "CollectDump"
        },
        {
          "Type": "CollectGCDump",
          "Settings": {
            "Egress": "monitorBlob"
          }
        }
      ]
    }
  }
}
Kubernetes ConfigMap
Egress__AzureBlobStorage__monitorBlob__accountUri: "https://exampleaccount.blob.core.windows.net"
Egress__AzureBlobStorage__monitorBlob__containerName: "dotnet-monitor"
Egress__AzureBlobStorage__monitorBlob__blobPrefix: "artifacts"
Egress__AzureBlobStorage__monitorBlob__accountKeyName: "MonitorBlobAccountKey"
Egress__Properties__MonitorBlobAccountKey: "accountKey"
Egress__FileSystem__artifacts__directoryPath: "/artifacts"
Egress__FileSystem__artifacts__intermediateDirectoryPath: "/intermediateArtifacts"
CollectionRuleDefaults__Actions__Egress: "artifacts"
CollectionRules__HighRequestCount__Trigger__Type: "AspNetRequestCount"
CollectionRules__HighRequestCount__Trigger__Settings__RequestCount: "10"
CollectionRules__HighRequestCount__Actions__0__Type: "CollectDump"
CollectionRules__HighRequestCount__Actions__1__Type: "CollectGCDump"
CollectionRules__HighRequestCount__Actions__1__Settings__Egress: "monitorBlob"
Kubernetes Environment Variables
- name: DotnetMonitor_Egress__AzureBlobStorage__monitorBlob__accountUri
  value: "https://exampleaccount.blob.core.windows.net"
- name: DotnetMonitor_Egress__AzureBlobStorage__monitorBlob__containerName
  value: "dotnet-monitor"
- name: DotnetMonitor_Egress__AzureBlobStorage__monitorBlob__blobPrefix
  value: "artifacts"
- name: DotnetMonitor_Egress__AzureBlobStorage__monitorBlob__accountKeyName
  value: "MonitorBlobAccountKey"
- name: DotnetMonitor_Egress__Properties__MonitorBlobAccountKey
  value: "accountKey"
- name: DotnetMonitor_Egress__FileSystem__artifacts__directoryPath
  value: "/artifacts"
- name: DotnetMonitor_Egress__FileSystem__artifacts__intermediateDirectoryPath
  value: "/intermediateArtifacts"
- name: DotnetMonitor_CollectionRuleDefaults__Actions__Egress
  value: "artifacts"
- name: DotnetMonitor_CollectionRules__HighRequestCount__Trigger__Type
  value: "AspNetRequestCount"
- name: DotnetMonitor_CollectionRules__HighRequestCount__Trigger__Settings__RequestCount
  value: "10"
- name: DotnetMonitor_CollectionRules__HighRequestCount__Actions__0__Type
  value: "CollectDump"
- name: DotnetMonitor_CollectionRules__HighRequestCount__Actions__1__Type
  value: "CollectGCDump"
- name: DotnetMonitor_CollectionRules__HighRequestCount__Actions__1__Settings__Egress
  value: "monitorBlob"