A C# DogStatsD client. DogStatsD is an extension of the StatsD metric server for Datadog.

See CHANGELOG for details.

Grab the package from NuGet, or get the source from here and build it yourself.

DogStatsD-CSharp-Client supports the following platforms:

• .NET Standard 1.3 or greater
• .NET Core 1.0 or greater
• .NET Framework 4.5.1 or greater

At start of your application, configure an instance of DogStatsdService class like this:

// The code is located under the StatsdClient namespace
using StatsdClient;

// ...

var dogstatsdConfig = new StatsdConfig
{
    StatsdServerName = "127.0.0.1",
    StatsdPort = 8125,
};

using (var service = new DogStatsdService())
{
    service.Configure(dogstatsdConfig);
}

See the full list of available DogStatsD Client instantiation parameters.

Supported environment variables:

• The client can use the DD_AGENT_HOST and (optionally) the DD_DOGSTATSD_PORT environment variables to build the target address if the StatsdServerName and/or StatsdPort parameters are empty.
• If the DD_ENTITY_ID enviroment variable is found, its value will be injected as a global dd.internal.entity_id tag. This tag will be used by the Datadog Agent to insert container tags to the metrics.

Where StatsdServerName is the hostname or address of the StatsD server, StatsdPort is the optional DogStatsD port number, and Prefix is an optional string that is prepended to all metrics.

For usage of DogStatsD metrics, events, and Service Checks the Agent must be running and available.

Here is an example to submit different kinds of metrics with DogStatsdService.

// The code is located under the StatsdClient namespace
using StatsdClient;

// ...

var dogstatsdConfig = new StatsdConfig
{
    StatsdServerName = "127.0.0.1",
    StatsdPort = 8125,
};

using (var service = new DogStatsdService())
{
    service.Configure(dogstatsdConfig);
    service.Increment("example_metric.increment", tags: new[] { "environment:dev" });
    service.Decrement("example_metric.decrement", tags: new[] { "environment:dev" });
    service.Counter("example_metric.count", 2, tags: new[] { "environment:dev" });

    var random = new Random(0);

    for (int i = 0; i < 10; i++)
    {
        service.Gauge("example_metric.gauge", i, tags: new[] { "environment:dev" });
        service.Set("example_metric.set", i, tags: new[] { "environment:dev" });
        service.Histogram("example_metric.histogram", random.Next(20), tags: new[] { "environment:dev" });
        System.Threading.Thread.Sleep(random.Next(10000));
    }
}  

Here is another example to submit different kinds of metrics with DogStatsd.

// The code is located under the StatsdClient namespace
using StatsdClient;

// ...

var dogstatsdConfig = new StatsdConfig
{
    StatsdServerName = "127.0.0.1",
    StatsdPort = 8125,
};

DogStatsd.Configure(dogstatsdConfig);
DogStatsd.Increment("example_metric.increment", tags: new[] { "environment:dev" });
DogStatsd.Decrement("example_metric.decrement", tags: new[] { "environment:dev" });
DogStatsd.Counter("example_metric.count", 2, tags: new[] { "environment:dev" });

var random = new Random(0);

for (int i = 0; i < 10; i++)
{
    DogStatsd.Gauge("example_metric.gauge", i, tags: new[] { "environment:dev" });
    DogStatsd.Set("example_metric.set", i, tags: new[] { "environment:dev" });
    DogStatsd.Histogram("example_metric.histogram", random.Next(20), tags: new[] { "environment:dev" });
    System.Threading.Thread.Sleep(random.Next(10000));
}
  
DogStatsd.Dispose(); // Flush all metrics not yet sent

After the client is created, you can start sending custom metrics to Datadog. See the dedicated Metric Submission: DogStatsD documentation to see how to submit all supported metric types to Datadog with working code examples:

• Submit a COUNT metric.
• Submit a GAUGE metric.
• Submit a SET metric
• Submit a HISTOGRAM metric
• Submit a DISTRIBUTION metric

Some options are suppported when submitting metrics, like applying a Sample Rate to your metrics or Tagging your metrics with your custom Tags.

After the client is created, you can start sending events to your Datadog Event Stream. See the dedicated Event Submission: DogStatsD documentation to see how to submit an event to Datadog Event Stream.

After the client is created, you can start sending Service Checks to Datadog. See the dedicated Service Check Submission: DogStatsD documentation to see how to submit a Service Check to Datadog.

Statsd has been removed in v6.0.0 because it is not thread safe and not efficient. Use DogStatsdService or DogStatsd instead:

• Methods from DogStatsdService and DogStatsd do not block when called except for Flush and Dispose.
• DogStatsdService and DogStatsd batch automatically several metrics in one datagram.

The version 6 (and above) of the Agent accepts packets through a Unix Socket datagram connection. Details about the advantages of using UDS over UDP are available in the Datadog DogStatsD Unix Socket documentation.

You can use unix domain socket protocol by setting StatsdServerName property to unix://YOUR_FULL_PATH, for example unix:///tmp/dsd.socket. Note that there are three / as the path of the socket is /tmp/dsd.socket.

var dogstatsdConfig = new StatsdConfig
{    
    StatsdServerName = "unix:///tmp/dsd.socket"  
};

The property StatsdMaxUnixDomainSocketPacketSize of StatsdConfig defines the maximum size of the payload. Values higher than 8196 bytes are ignored.

The feature is not supported on Windows platform. Windows has support for unix domain socket, but not for unix domain socket of type Dgram (SocketType.Dgram).

On MacOS Mojave, setting more than 2048 bytes for StatsdMaxUnixDomainSocketPacketSize is experimental.

1. Restore packages

dotnet restore

2. Run the tests

dotnet test tests/StatsdClient.Tests/

To suggest a feature, report a bug, or general discussion, create a new issue in the Github repo.

dogstatsd-csharp-client is forked from Goncalo Pereira's original StatsD client.

Copyright (c) 2012 Goncalo Pereira and all contributors. See MIT-LICENCE.md for further details.

Thanks to Goncalo Pereira, Anthony Steele, Darrell Mozingo, Antony Denyer, and Tim Skauge for their contributions to the original client.