OpenDotNetDiagnostics.Core 1.0.0-beta5

This is a prerelease version of OpenDotNetDiagnostics.Core.
dotnet add package OpenDotNetDiagnostics.Core --version 1.0.0-beta5                
NuGet\Install-Package OpenDotNetDiagnostics.Core -Version 1.0.0-beta5                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="OpenDotNetDiagnostics.Core" Version="1.0.0-beta5" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add OpenDotNetDiagnostics.Core --version 1.0.0-beta5                
#r "nuget: OpenDotNetDiagnostics.Core, 1.0.0-beta5"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install OpenDotNetDiagnostics.Core as a Cake Addin
#addin nuget:?package=OpenDotNetDiagnostics.Core&version=1.0.0-beta5&prerelease

// Install OpenDotNetDiagnostics.Core as a Cake Tool
#tool nuget:?package=OpenDotNetDiagnostics.Core&version=1.0.0-beta5&prerelease                

Welcome to Open DotNET Diagnostics

Integrate .NET diagnostics tools into your code and seamlessly deliver results to multiple destinations.

Vision for the project

Please note that while this repository is open source, it is not a Microsoft/dotnet repository. We welcome contributions from anyone interested in improving our solution.

Our approach prioritizes the developer experience and therefore requires some code instrumentation, typically just a few lines. If you prefer an operational approach that doesn't require any code changes, we recommend checking out the official dotnet-monitor repository.

Get Started (dotnet-counters)

Assuming you have an ASP.NET Core WebAPI project:

  1. Add NuGet packages:

  2. Instrument the code to register the proper service and map the end point, for example:

    var builder = WebApplication.CreateBuilder(args);
    
    // Register `dotnet-counters` service and its sink.
    builder.Services.AddDotNetCounters(pipeline => {
        pipeline.AddLocalFileSink()
    });
    
    var app = builder.Build();
    
    app.MapGet("/", () => "Hello World!");
    
    // Add an endpoint of `/dotnet-counters`
    app.MapDotNetCounters("/dotnet-counters");
    app.Run();
    

    Other sinks, for example, Azure Blob or Application Insights are also supported. See wiki for more details.

  3. Optionally, customize the settings, for example, you could specify a invoking secret than the default of 1123 by putting this in your appsettings.json:

    "DotNetCounters": {
        "InvokingSecret": "1111"
    },
    
  4. Run your app.

  5. To enable dotnet-counters, invoke a HttpPUT on the endpoint, for example:

    • Set headers:
      • Content-Type: application json

      • x-invoking-secret: 1111

        Invoking dotnet-counters

      • Use the body to control whether to enable or disable the dotnet counters:

        Invoking dotnet-counters

    Tips: You can turn off dotnet-counters at anytime by invoke another PUT request with isEnabled parameter set to false.

  6. Get the output

    • In a local environment, by default, the file is in %tmp%, you will have files like Counters_2023031600.csv;
    • In Azure App Service, the default output path would be %HOME%/LogFiles/Application/, and the file name would carry a unique id for the service instance, like this:
      • Counters_82177b41d89d4b2dce789b4903a7e0dc0a76412697ac6069b750097059c09ed7_2023031523.csv Counters Output on Kudu
  7. And you shall be able to download analysis the result in tools you already familiar with, for example, in the Excel:

    Analysis example in excel for working set

    What we see: it is a pretty small amount of working set used over the period, yet we could still see dips, probably GC?

Scenarios

For more, read the wiki.

Vision

We aim to alleviate the following pain points:

  1. You no longer need to deliver dotnet diagnostic tool binaries such as dotnet-counters, dotnet-trace, or dotnet-dump to your environment..

    1. Some environments, such as containers, make it inconvenient to add additional binaries, while others, like Azure App Service/WebSite, are sandboxed and unable to run .NET tools.
    2. With our solution, you can enjoy a consistent experience whether you are diagnosing issues locally or remotely.
  2. You no longer need to export diagnostic data, such as dotnet-counter output, from a constrained environment.

    1. By adding proper sinks, you can easily access these files through Kudu or Azure Blob Storage and so on.
    2. Your data will persist externally even if your machine or containers are recycled.
  3. With our solution, you can write once and run everywhere, including locally, on Azure WebSite, in containers, or on AKS, with a unified experience.

Road map

  1. Add support for more .NET diagnostics tools.
  2. Update to support more complex environments - scaled out multiple instances.
  3. Support triggers - that automatically starts the diagnostic tools.
  4. Add guidance for extending sinks.
DotNet Tools Local Environment Azure App Service Container Remarks
dotnet-counters OpenDotNetDiagnostics.Counters.WebEndpoints +<br /> OpenDotNetDiagnostics.Counters.Sinks.LocalFile OpenDotNetDiagnostics.Counters.WebEndpoints +<br /> OpenDotNetDiagnostics.Counters.Sinks.LocalFile or OpenDotNetDiagnostics.Counters.Sinks.AzureBlob OpenDotNetDiagnostics.Counters.WebEndpoints +<br /> OpenDotNetDiagnostics.Counters.Sinks.AzureBlob MVP
dotnet-dump Planning Planning Planning Coming next
dotnet-trace Planning Planning Planning Backlog

There are quite a few to crewing through. Please feel free to contact if want to contribute.

  • Core projects

    • Core - fundamental utilities, data contracts, abstractions.
    • Counters - dotnet-counters specific implementations.
  • Endpoints

    • dotnet-counters
      • WebEndpoints - expose dotnet-counters as a WebAPI endpoint. Default to PUT /dotnet-counters.
  • Sinks

    • dotnet-counters
      • Local file - beta, outputs data to local file.
      • Azure Blob - beta, outputs data to Azure Storage for easy access.
      • Application insights - beta, outputs data to Application Insights for powerful query.
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (5)

Showing the top 5 NuGet packages that depend on OpenDotNetDiagnostics.Core:

Package Downloads
OpenDotNetDiagnostics.Counters.Sinks.LocalFile

Integrate .NET diagnostics tools into your code and seamlessly deliver results to multiple destinations.

OpenDotNetDiagnostics.Counters.Sinks.AzureBlob

Integrate .NET diagnostics tools into your code and seamlessly deliver results to multiple destinations.

OpenDotNetDiagnostics.Counters

Integrate .NET diagnostics tools into your code and seamlessly deliver results to multiple destinations.

OpenDotNetDiagnostics.Counters.Sinks.ApplicationInsights

Integrate .NET diagnostics tools into your code and seamlessly deliver results to multiple destinations.

OpenDotNetDiagnostics.JobDispatchers.AzureBlob

Integrate .NET diagnostics tools into your code and seamlessly deliver results to multiple destinations.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.0.0-beta5 98 6/9/2023
1.0.0-beta4 97 4/12/2023
1.0.0-beta3 91 4/6/2023
1.0.0-beta2 88 4/6/2023
1.0.0-beta1 94 3/31/2023