OpenDotNetDiagnostics.Core
1.0.0-beta5
dotnet add package OpenDotNetDiagnostics.Core --version 1.0.0-beta5
NuGet\Install-Package OpenDotNetDiagnostics.Core -Version 1.0.0-beta5
<PackageReference Include="OpenDotNetDiagnostics.Core" Version="1.0.0-beta5" />
paket add OpenDotNetDiagnostics.Core --version 1.0.0-beta5
#r "nuget: OpenDotNetDiagnostics.Core, 1.0.0-beta5"
// 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.
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:
Add NuGet packages:
- OpenDotNetDiagnostics.Counters.WebEndpoints - to expose an endpoint for enabling/disabling
dotnet-counters
. - OpenDotNetDiagnostics.Counters.Sinks.LocalFile - to export the data to a local file (and in app service, to application logs folder).
- OpenDotNetDiagnostics.Counters.WebEndpoints - to expose an endpoint for enabling/disabling
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.
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" },
Run your app.
To enable
dotnet-counters
, invoke aHttpPUT
on the endpoint, for example:- Set headers:
Content-Type: application json
x-invoking-secret: 1111
Use the body to control whether to enable or disable the dotnet counters:
Tips: You can turn off
dotnet-counters
at anytime by invoke another PUT request withisEnabled
parameter set to false.- Set headers:
Get the output
- In a local environment, by default, the file is in
%tmp%
, you will have files likeCounters_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
- In a local environment, by default, the file is in
And you shall be able to download analysis the result in tools you already familiar with, for example, in the Excel:
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
- Basic settings of the pipeline and the customizations
- Enable
dotnet-counters
for CPU usage monitoring
For more, read the wiki.
Vision
We aim to alleviate the following pain points:
You no longer need to deliver dotnet diagnostic tool binaries such as dotnet-counters, dotnet-trace, or dotnet-dump to your environment..
- 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.
- With our solution, you can enjoy a consistent experience whether you are diagnosing issues locally or remotely.
You no longer need to export diagnostic data, such as
dotnet-counter
output, from a constrained environment.- By adding proper sinks, you can easily access these files through Kudu or Azure Blob Storage and so on.
- Your data will persist externally even if your machine or containers are recycled.
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
- Add support for more .NET diagnostics tools.
- Update to support more complex environments - scaled out multiple instances.
- Support triggers - that automatically starts the diagnostic tools.
- Add guidance for extending sinks.
Recommended Setup Matrix
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
.
- WebEndpoints - expose dotnet-counters as a WebAPI endpoint. Default to
- 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.
- dotnet-counters
Product | Versions 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. |
-
net6.0
- Azure.Identity (>= 1.8.2)
- Microsoft.Extensions.Configuration (>= 7.0.0)
- Microsoft.Extensions.Hosting.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Logging.Abstractions (>= 7.0.0)
- Microsoft.Extensions.Options (>= 7.0.1)
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 |