DatadogStatsD 0.3.0

dotnet add package DatadogStatsD --version 0.3.0                
NuGet\Install-Package DatadogStatsD -Version 0.3.0                
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="DatadogStatsD" Version="0.3.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add DatadogStatsD --version 0.3.0                
#r "nuget: DatadogStatsD, 0.3.0"                
#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 DatadogStatsD as a Cake Addin
#addin nuget:?package=DatadogStatsD&version=0.3.0

// Install DatadogStatsD as a Cake Tool
#tool nuget:?package=DatadogStatsD&version=0.3.0                

DatadogStatsD

Full featured DogStatsD client:

  • Count, Histogram, Gauge, Distribution, Set
  • Events
  • Service Checks
  • UDP or UDS transport
  • Performance (up to 30x faster than the official library) - Metrics are aggregated and the submissions are batched
  • Back pressure - Transport drops new metrics when it's falling behind
  • Telemetry - Metrics to monitor communication between the agent and this client

Installation

DatadogStatsD targets both .NET Standard 2.0 & 2.1.

dotnet add package DatadogStatsD

Examples

// Create a DogStatsD client with the default configuration, that is, UDP on port 8125.
await using var dogStatsD = new DogStatsD();

// Pass a DogStatsDConfiguration instance to configure the client. For example, to
// use a unix socket, a common prefix and common tags to all your metrics:
await using var dogStatsD = new DogStatsD(new DogStatsDConfiguration
{
    EndPoint = new UnixDomainSocketEndPoint("/path/to/unix.socket"),
    Namespace = "foo",
    ConstantTags = new[] { KeyValuePair.Create("service", "service_foo") },
});

// Create a COUNT metric named "requests" with the tag "environment:dev". The method
// throws if the metric name or tags are invalid (e.g. too long, invalid characters)
// to avoid using metrics that won't be accepted by the agent.
using var requests = dogStatsD.CreateCount("requests", new[] { KeyValuePair.Create("env", "dev") });
requests.Increment(); // requests++
requests.Decrement(); // requests--
// Because counters are aggregated client-side, nothing is sent here since the metric
// was incremented once then decremented once which results in zero.

// No client-side aggregation is possible for histograms. In performance sensitive
// scenario, a sample rate can be used to only send metrics a percentage of the time
// and a correction is applied server-side. Note that the library is very fast. In the
// benchmarks, Histogram.Sample takes 250 ns to execute.
var latency = dogStatsD.CreateHistogram("latency", sampleRate: 0.5);
latency.Sample(5.423);
latency.Sample(1.27);

// Gauges use a function that is periodically evaluated and send to the agent. Here,
// until you dispose the object. you will get a graph of the number of threads in
// your process.
using var threads = dogStatsD.CreateGauge("threads", () => Process.GetCurrentProcess().Threads.Count);
// You can also manually update the gauge.
threads.Update(25);

dogStatsD.RaiseEvent(AlertType.Info, title: "Bad thing happened", message: "This happened");
dogStatsD.SendServiceCheck("is_connected", CheckStatus.Ok);

Benchmark

Benchmark comparing performance of this library (DatadogStatsD), when sending 10000 metrics, with DataDog/dogstatsd-csharp-client (DogStatsDService) and neuecc/DatadogSharp (DatadogSharp). Sources can be found in DatadogStatsD.Benchmark.

Count, Gauge, Set

Method Mean Error StdDev Gen 0 Gen 1 Gen 2 Allocated
DatadogStatsD 81.02 us 0.078 us 0.073 us - - - -
DogStatsDService 2,515.55 us 44.406 us 39.365 us 574.2188 3.9063 - 901739 B
DatadogSharp 87,210.79 us 473.027 us 419.326 us 3000.0000 - - 4879285 B

This library aggregates for 10 seconds (DogStatsD flush interval) counts, gauges and sets. So for 10000 increments, one packet is sent, hence the ~0 bytes allocated.

Histogram, Distribution

Method Mean Error StdDev Gen 0 Gen 1 Gen 2 Allocated
DatadogStatsD 2.543 ms 0.0504 ms 0.0581 ms - - - 636 B
DogStatsDService 2.502 ms 0.0351 ms 0.0328 ms 574.2188 3.9063 - 901715 B
DatadogSharp 87.172 ms 0.3307 ms 0.3093 ms 3000.0000 - - 4879343 B

For those metrics, the library lets DogStatsD agent do the aggregation, so with a sample rate of 1.0, each call to Histogram.Update will be sent to the agent.

Even though execution times might seem similar between this library (DatadogStatsD) and the official one (DogStatsDService), during the 250ns (2.5ms / 10000 ops), the former serializes the metric and enqueue it, ready to be sent to the agent, when the latter only enqueues the values passed to the DogStatsDService.Histogram method and the serialization is done in a dedicated thread.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  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. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.3.0 261,340 10/26/2020
0.2.5 520 10/8/2020
0.2.4 506 7/26/2020
0.2.3 530 6/18/2020
0.2.2 428 6/14/2020
0.2.1 391 6/11/2020
0.2.0 393 6/10/2020
0.1.3 449 4/28/2020
0.1.2 667 3/30/2020
0.1.1 490 3/20/2020
0.1.0 497 3/20/2020