DOCSEARCHbyAlgolia
Submit Docs

dotnet-monitor Documentation

repository·main·Indexed 20 days ago

https://github.com/dotnet/dotnet-monitor

A diagnostic tool for capturing artifacts such as logs, traces, and process dumps from .NET applications. It provides a unified HTTP API for on-demand collection and supports automated rule-based collection via Triggers. The tool supports monitoring applications running on .NET Core 3.1, .NET 5, .NET 6, .NET 7, and later versions, with specific installation and runtime requirements for versions 7.0 through 9.0.

Tokens
75.3K
Snippets
192
Records
400
Agent score
71%

What's inside dotnet-monitor

  1. Overview of dotnet monitor configuration areas

    main

    The dotnet monitor configuration is extensive and allows you to override default behaviors. Key configuration areas include:

    • Configuration Sources: Methods for using JSON files, Environment variables, or Kubernetes for configuration.
    • View Merged Configuration: A diagnostic command to see the final configuration applied after all sources are merged.
    • Diagnostic Port Configuration: Settings for how dotnet monitor communicates with .NET processes via their diagnostic port.
    • Kestrel Configuration: Settings for how dotnet monitor listens for HTTP requests.
    • Storage Configuration: Specifies directories shared between dotnet monitor and target applications for diagnostic features like memory dumps and stack traces.
    • Default Process Configuration: Determines which process is used for metrics or when a process is not specified in a query.
    • Metrics Configuration: Configures the /metrics endpoint for live metrics collection.
    • Egress Configuration: Enables storing artifacts (dumps, traces) in a hosting-environment-suitable manner rather than streaming them back directly.
    • In-Process Features Configuration: Configures features that require loading libraries into target applications (note: this may impact memory and CPU).
    • Cross-Origin Resource Sharing (CORS) Configuration: Settings for HTTP CORS behavior.

  2. Overview of the dotnet-monitor HTTP API

    main

    The dotnet-monitor HTTP API allows for on-demand extraction of diagnostic information and artifacts from discoverable .NET processes. It supports .NET Core 3.1 and .NET 5+ applications. Note that for .NET Core 3.1 applications, certain diagnostic information may be unavailable.

    Some features are marked as **[Experimental]** in the detailed route documentation.

  3. Overview of dotnet-monitor capabilities

    main

    dotnet-monitor is a diagnostic tool designed to capture diagnostic artifacts (such as logs, traces, and process dumps) in an operator-driven or automated manner. It provides a unified way to collect these artifacts regardless of the environment where your .NET application is running.

    There are two primary mechanisms for artifact collection:

    1. HTTP API: Used for on-demand collection. You can call specific API endpoints when an issue is detected to gather information immediately.
    2. Triggers: Used for rule-based, always-on collection. You can configure rules to automatically collect artifacts when specific conditions are met (e.g., collecting a process dump automatically when CPU usage remains high for a sustained period).

  4. Overview of `dotnet monitor`

    main
    dotnet monitor is a tool designed to simplify access to diagnostics information in a .NET process. It provides a consistent HTTP API for collecting diagnostics artifacts—such as logs, traces, and process dumps—regardless of whether the application is running in a local environment, Docker, or Kubernetes. This abstraction helps overcome the challenges of varying local and production environments when collecting diagnostic data.

  5. Use the /collectionrules route to monitor collection rules

    main

    The /collectionrules route is used to report and inspect the state of configured collection rules in dotnet-monitor. You can use this route to check the status of rules across all processes or drill down into a specific process.

    Important Note: Process information (such as IDs, names, and environment variables) is dynamic. Processes may start or stop between API calls, so information retrieved from these endpoints may change between invocations.

  6. Collect .nettrace formatted traces via the Traces API

    main

    The Traces API allows you to collect diagnostic traces in the .nettrace format without requiring a profiler. You can capture traces using either predefined trace profiles or by specifying a custom set of event providers in the request body.

    Important Note: Process information (such as IDs, names, and environment details) is volatile and may change between API invocations. Processes may start or stop during the lifecycle of your requests, which can lead to inconsistencies in the process metadata returned.

  7. Capture logs using the Logs API

    main

    The Logs API allows you to collect logs from a specific process that uses the ILogger<> infrastructure.

    Prerequisites

    To capture logs, the LoggingEventSource provider must be enabled within the target process.

    Available Operations

    • Get Logs: Captures log statements from a process at a specified log level or at application-defined categories and levels.
    • Get Custom Logs: Captures log statements from a process using specific settings provided in the request body.
    NOTE

    Process information (such as IDs, names, and environment) is dynamic and may change between API invocations. Processes may start or stop between calls, which can affect the availability of process-specific data.

  8. Use DOTNETMONITOR_ prefix to override environment variables

    main

    Environment variables prefixed with DotnetMonitor_ (single underscore) have higher precedence than standard environment variables. This allows you to override settings provided by the host environment.

    Example: If DefaultProcess__Filters__0__Key is set to dotnet, but you also set DotnetMonitor_DefaultProcess__Filters__0__Key to myapp, dotnet monitor will use myapp.

    export DotnetMonitor_DefaultProcess__Filters__0__Key="myapp"
export DefaultProcess__Filters__0__Key="dotnet"

  9. Use Trigger Shortcuts for EventCounters

    main

    Trigger Shortcuts provide a simplified syntax for commonly used EventCounter triggers. They offer improved defaults and range validation while reducing configuration verbosity by removing the need to manually specify the ProviderName or CounterName.

    When using a shortcut, dotnet monitor automatically converts it into a standard EventCounter trigger using the appropriate predefined defaults.

  10. How collection rules work in dotnet monitor

    main

    A collection rule allows dotnet monitor to automatically collect diagnostic artifacts based on specific conditions within discovered processes.

    Prerequisite: Collection rules are only enabled when dotnet monitor is running in Listen mode.

    Rule Composition

    A collection rule consists of four components:

    1. Filters: Determines which processes the rule applies to (e.g., by process name, ID, or command line). If no filters are provided, the rule applies to all discovered processes.
    2. Trigger: The condition being monitored in the target process. When the trigger is satisfied, the rule executes its actions.
    3. Actions: A list of operations or external executables to run once the trigger is satisfied. Actions are executed in the order they are specified.
    4. Limits: Constraints applied to the rule or action execution (e.g., maximum number of executions or duration).

    Lifecycle

    1. Discovery: When a process is discovered, dotnet monitor checks it against the rule's Filters.
    2. Monitoring: If the process matches, the Trigger starts monitoring. (Note: The Startup trigger is satisfied immediately upon application).
    3. Execution: Once the trigger is satisfied, the Actions are executed sequentially.
    4. Restart: After the action list completes, the rule restarts the Trigger to continue monitoring.

  11. Understand the .NET Monitor API Key format

    main

    API Keys (or MonitorApiKeys) used in dotnet monitor are JSON Web Tokens (JWTs) as defined by RFC 7519.

    Because the API Key is a Bearer token, it must be treated as a secret and always transmitted over TLS or another protected protocol.

    While you can manually construct your own API Keys, it is highly recommended to use the generatekey command instead.

  12. Configure dotnet monitor in Listen Mode

    main

    In listen mode, dotnet monitor establishes a diagnostic communication channel via a Unix Domain Socket.

    Communication Setup

    1. Endpoint Name: Use the DOTNETMONITOR_DiagnosticPort__EndpointName environment variable to specify the Unix Domain Socket path.
    2. Application Connection: The application container must set the DOTNET_DiagnosticPorts environment variable to the same socket path so the runtime can communicate with dotnet monitor.
    3. Startup Behavior: The application runtime will be suspended (no managed code execution) until it successfully establishes communication with dotnet monitor.

    Simplified Configuration (7.0+)

    If you are using version 7.0 or later, you can simplify setup by using a shared path:

    • Set DOTNETMONITOR_Storage__DefaultSharedPath to a shared volume.
    • Set DOTNETMONITOR_DiagnosticPort__ConnectionMode to Listen.
    • This automatically creates a Unix Domain Socket named dotnet-monitor.sock under the default shared path, removing the need to manually set DOTNETMONITOR_DiagnosticPort__EndpointName.