What is new in dotnet monitor?

Table of Content

Introduction

Dotnet monitor is an experimental tool utilized to attain simple access on diagnostic information in the process. Now, dotnet-monitor has support in the tools of .NET ecosystem. dotnet monitor will provide full support when the first stable version will release later this year.

In production environments and diverse local can make collecting diagnostics artifacts (e.g., traces, logs, process, dumps) challenging when running a dotnet application. The aim of dotnet monitor is - regardless of where your application is run, simplify the process by exposing a consistent REST API.

This blog includes the details about some of the major new features in the preview4 release of dotnet monitor:

1. Egress providers
2. Custom metrics
3. Security and Hardening

Getting Started

dotnet monitor is available from the two different distributed mechanisms.

1. As .NET global tool; and
2. As a container image available via the MCR (Microsoft Container Registry)

The setup instructions for dotnet monitor modify based on the target environment.

Dotnet configuration binds to two different groups of URLs in the default configuration. The URLs which is controlled via the --urls (defaults to http://localhost:52323) that exposes all the collection endpoints and the URLs which is controlled via the --metricsUrls parameters (default to http://localhost:52325). It is strongly recommended that you do not publicly expose the endpoints because diagnostics artifacts such as dumps, logs, and traces can leak the sensitive information about the application.

.Net global tool

As a pre-requisite, the dotnet monitor global tool requires a .NET 3.1 or installed newer SDK. You can install a new SDK from the Download .NET webpage if you do not have a new enough SDK.

On Nuget, you can see the latest public preview of dotnet monitor and you can download the latest version of dotnet monitor tool using the following command:

dotnet tool install -g dotnet-monitor --version 5.0.0-preview.4.*

You can update the dotnet monitor if you have already installed it using the following command:

dotnet tool update -g dotnet-monitor --version 5.0.0-preview.4.*

Container image

On MCR (Microsoft Container Registry), You can see the latest public preview of the dotnet monitor container image and you can use the following command if you want to pull the image:

docker pull mcr.microsoft.com/dotnet/monitor:5.0.0-preview.4

Egress Providers

We could only use one way to egress diagnostic artifacts from dotnet monitor and that is via the HTTP response stream in previous previews and this works well for over-reliable connections but this becomes increasingly challenging for less reliable connections and very large artifacts.

You can configure dotnet monitor to egress artifacts to other destinations in preview4: the local file system and Azure Blob Storage. It is also possible if you want to specify the multiple egress providers via configuration as shown in the example below:

Example

{
    "Egress": {
        "Providers": {
            "sampleBlobStorageEgressProvider": {
                "accountUri": "https://contoso.blob.core.windows.net",
                "containerName": "dotnet-monitor",
	       "type": "azureBlobStorage",
                "blobPrefix": "artifacts",
                "accountKeyName": "MonitorBlobAccountKey"
            }
        },
        "Properties": {
            "MonitorBlobAccountKey": "accountKey"
        }
    }
}

Once it is configured, then at the time of triggering the artifact collection via an HTTP request, you can specify that which egress provider will use. With the above configuration, now you can make the request like the following:

GET /dump/?egressProvider=sampleBlobStorageEgressProvider HTTP/1.1

Look at the egress configuration documentation for more detailed instructions on configuring egress providers.

Custom metrics

To add the collection of Microsoft.AspNetCore.Hosting metrics and System.Runtime, now it is possible to collect additional metrics (emitted via EventCounters) in the Prometheus exposition format for exporting.

Example

{
  "Metrics": {
    "Providers": [
      {
        "ProviderName": "Microsoft-AspNetCore-Server-Kestrel"
      }
    ]
  }
}

Look at the metrics configuration documentation for more detailed instructions about collecting custom metrics.

Security and Hardening

In production environments, authentication requirement is one of the parts of the work that’s gone into hardening dotnet monitor to make it suitable for deployment. Additionally, if you want to protect the credentials which were sent over the wire as part of authentication then dotnet monitor will also default to requiring that the underlying channel which uses HTTPS.

In preview4 the /trace, /dump, /gcdump, /processes, and /logs API endpoints will require authentication and the /metrics endpoint will still be available on a separately configured metricsUrl without authentication for scraping from scrapping via exterior tools like Prometheus.

In the scenario of the local machine, if .NET SDK is already installed then dotnet monitor will default to using HTTPS development certificate of ASP.NET Core. For secure experience, we also enable Windows authentication as another option to API token auth.

You can use the official documentation that shows more detailed instructions about some steps to configuring dotnet monitor securely that have been omitting for brevity in the blog.

Generating an SSL Certificate

If you want to configure dotnet monitor to run securely, you have to generate an SSL certificate with an EKU (Extended Key Usage) for server usage. You can either generate a self-signed certificate or request this certificate from your certificate authority.

By invoking the dotnet dev-certs tool, if you wish to generate another self-signed certificate for use on any other machine then you may do so.

dotnet dev-certs https -export-path self-signed-certificate.pfx -p 

Generating an API token

To use an API token, you should generate a 32-byte cryptographically random secret.

dotnet monitor generatekey

The output produced from this will look like this:

Example

Authorization: MonitorApiKey H2O2yT1c9yLkbDnU9THxGSxje+RhGwhjjTGciRJ+cx8=
ApiKeyHash: B4D54269DB7D948A8C640DB65B46D2D705A516134DA61CD97E424AC08E5021ED
ApiKeyHashType: SHA256

Once you have both an API Token and an SSL certificate generated, to respond to authenticated HTTP requests over a secure TLS (Transport Layer Security) channel you can configure dotnet monitor using the following configuration:

Example

{
  "ApiAuthentication": {
    "ApiKeyHash": "",
    "ApiKeyHashType": "SHA256"
  },
  "Kestrel": {
    "Certificates": {
      "Default":{
        "Path": "",
        "Password": ""
      }
    }
  }
}

Your browser will automatically handle the Windows authentication challenge when using Windows Authentication. You must specify it via the Authorization header on HTTP requests when you are using an API Key.

Example

curl.exe -H "Authorization: MonitorApiKey H2O2yT1c9yLkbDnU9THxGSxje+RhGwhjjTGciRJ+cx8="

Roadmap

Until the stable version of dotnet monitor will be released later this year, the dotnet monitor will continue to iterate with monthly updates.

Conclusion

In this blog, we have seen the major new updates in dotnet monitor and how to use it by the example which is helpful to makes it easier to get access to diagnostics information in a dotnet process.