What’s new in dotnet monitor

Sourabh

We’ve previously introduced dotnet monitor as an experimental tool to access diagnostics information in a dotnet process. We’re now pleased to announce dotnet monitor has graduated to a supported tool in the .NET ecosystem. dotnet monitor will be fully supported beginning with our first stable release later this year.

If you are new to dotnet monitor , we recommend checking out the official documentation which includes walkthroughs on using dotnet monitor on a local machine, with Docker, and Kubernetes,

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

  • Egress providers
  • Custom metrics
  • Security and Hardening

Getting Started

dotnet monitor is available via two different distribution mechanisms:

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

.NET global tool

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

The latest public preview of dotnet monitor is available on Nuget. You can download the latest version using the following command:

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

If you already have dotnet monitor installed and want to update:

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

Container image

The latest public preview of the dotnet monitor container image is available on MCR. You can pull the latest image using the following command:

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

Egress providers

In previous previews, the only way to egress diagnostic artifacts from dotnet monitor was via the HTTP response stream. While this works well over reliable connections, this becomes increasingly challenging for very large artifacts and less reliable connections.

In preview4, you can configure dotnet monitor to egress artifacts to other destinations: Azure Blob Storage and the local filesystem. It is possible to specify multiple egress providers via configuration as shown in the example below:

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

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

GET /dump/?egressProvider=sampleBlobStorageEgressProvider HTTP/1.1

For more detailed instructions on configuring egress providers, look at the egress configuration documentation

Custom metrics

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

You can configure dotnet monitor to collect additional metrics as shown in the example below:

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

For more detailed instructions on collecting custom metric, look at the metrics configuration documentation

Security and Hardening

Requiring authentication is part of the work that’s gone into hardening dotnet monitor to make it suitable for deployment in production environments. Additionally, to protect the credentials sent over the wire as part of authentication, dotnet monitor will also default to requiring that the underlying channel uses HTTPS.

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

In the local machine scenario with .NET SDK already installed, dotnet monitor will default to using ASP.NET Core HTTPS development certificate. If running on Windows, we also enable Windows authentication for secure experience as an alternative to API token auth.

Some steps in configuring dotnet monitor securely have been omitted for brevity in the blog post. We recommend looking at the official documentation for detailed instructions.

To get started with dotnet monitor in production, you will require an SSL certificate and an API Token.

Generating an SSL Certificate.

To configure dotnet monitor to run securely, you will need to generate an SSL certificate with an EKU for server usage. You can either request this certificate from your certificate authority or generate a self-signed certificate.

If you wish to generate another self-signed certificate for use on another machine you may do so by invoking the dotnet dev-certs tool:

dotnet dev-certs https -export-path self-signed-certificate.pfx -p <your-cert-password>

Generating an API token

You should generate a 32-byte cryptographically random secret to use an API token:

dotnet monitor generatekey

That should produce an output that resembles this:

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

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

{
  "ApiAuthentication": {
    "ApiKeyHash": "<HASHED-TOKEN>",
    "ApiKeyHashType": "SHA256"
  },
  "Kestrel": {
    "Certificates": {
      "Default":{
        "Path": "<path-to-cert.pfx>",
        "Password": "<your-cert-password>"
      }
    }
  }
}

When using Windows Authentication, your browser will automatically handle the Windows authentication challenge. If you are using an API Key, you must specify it via the Authorization header on HTTP requests

curl.exe -H "Authorization: MonitorApiKey H2O2yT1c9yLkbDnU9THxGSxje+RhGwhjjTGciRJ+cx8=" https://localhost:52323/processes

Roadmap

We will continue to iterate on dotnet monitor with monthly updates until we’ll release a stable version later this year. dotnet monitor supports .NET Core 3.1 as well as .NET 5 and later.

Conclusion

We are excited to introduce this major update to dotnet monitor and want your feedback. Let us know what we can do to make it easier to diagnose what’s wrong with your .NET application.

Let us know what you think!.

4 comments

Comments are closed. Login to edit/delete your existing comments

  • Omri Harary

    Very excited to see this, I’ve been waiting eagerly since it was first announced. To the team: good work!

    As a note, the documentation under “getting started” seems to be missing

  • Darragh Jones

    A grafana dashboard to go along with these metrics would be a great addition!

  • John King

    we do not need a global tool , we need APM (Self Hosted), with dotnet global tool, does that means that we need install the .net SDK , and I believe you told us to install dotnet runtime to the server instead of SDK.

    I do not understand why Microsoft is fixation on “toy” project, Should not MS lead us to develop the rich Ecosystem ?

    Look at the dotnet now:
    AMP: Java / go / rust
    Distributed Cache : C (redis) and No Windows version
    index Search : Java
    Kafka : Java
    many and many : either Java or Go or Rust

    Yes , this is our Ecosystem, there no such thing at all !!!!!!
    and the fact is Enterprise continue the journey of switch .Net to Java/Node/Go (with the love of C#)

    Last ,

    why dotnet goes this situation ? because it has an $ evolved Dad ?
    why there not “Apache Foundation” for .Net ?
    what does the “Dotnet Foundation” do ? and why there no project under the name of “DotnetFoundation.****” ?
    why the MS’s Asp.Net Core do not have a good Modular System build in , and we must do the heavy change like “Abp” did, and just look at the Spring. it bring best practice and reusable library to every java develop.

    if the answer is “we want you to use azure” , then please just stop the development of .Net ! just do not make a pfatfrom/lanague as a weapon. and give C#/Dotnet a good organization to maintain (unity, JetBrains) because the C# is such damn good .

    MS lead us from .net framework 3.x to a gap of .net framework 4.x , and lead us from webform to mvc , aspx to cshtml, wcf to rest , and then lead us from .net framework to dnx, and to .net core, but when does the journey stop ? when we can have rich ecosystem to develop our app easier ?

    and in the end, let me stop complain and ask : “Will MS want to lead us to have our own rich ecosystem instead of just use everything from other language” ?