DatadogStatsD 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

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

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.