A thread-safe C# .NET client for reporting metrics to various providers, including Bosun (Time Series Alerting Framework), SignalFx and DataDog. This library is more than a simple wrapper around relevant APIs. It is designed to encourage best-practices while making it easy to create counters and gauges, including multi-aggregate gauges. It automatically reports metrics on an interval and handles temporary API or network outages using a re-try queue.

VIEW CHANGES IN StackExchange.Metrics 1.0

First, create a MetricsCollector object. This is the top-level container which will hold all of your metrics and handle sending them to the Bosun API. Therefore, you should only instantiate one, and make it a global singleton.

var collector = new MetricsCollector(new BosunOptions(ex => HandleException(ex))
{
	MetricsNamePrefix = "app_name.",
	Endpoints = new[] {
		new MetricEndpoint("Bosun", new BosunMetricHandler("http://bosun.mydomain.com:8070")),
		new MetricEndpoint("DataDog", new DataDogMetricHandler("http://datadog.mydomain.com:1234", "API_KEY", "APP_KEY")),
	},
	PropertyToTagName = NameTransformers.CamelToLowerSnakeCase,
	DefaultTags = new Dictionary<string, string> 
		{ {"host", NameTransformers.Sanitize(Environment.MachineName.ToLower())} }
});

All of the available options are documented in the BosunOptions class or the individual metric handlers:

• BosunMetricHandler
• DataDogMetricHandler
• DataDogStatsdMetricHandler
• LocalMetricHandler
• SignalFxMetricHandler

Create a counter with only the default tags:

var counter = collector.CreateMetric<Counter>("my_counter", "units", "description");

Increment the counter by 1:

counter.Increment();

Tags are used to subdivide data in various metric platforms. In BosunReporter, tag sets are defined as C# classes. For example:

public class SomeCounter : Counter
{
	[BosunTag] public readonly string SomeTag;
	
	public RouteCounter(string tag)
	{
		SomeTag = tag;
	}
}

For more details, see the Tags Documentation.

There are two high-level metric types: counters and gauges.

Counters are for counting things. The most common use case is to increment a counter each time an event occurs. Bosun/OpenTSDB normalizes this data and is able to show you a rate (events per second) in the graphing interface. BosunReporter has two built-in counter types.

Gauges describe a measurement at a point in time. A good example would be measuring how much RAM is being consumed by a process. BosunReporter provides several different built-in types of gauges in order to support different programmatic use cases, but Bosun itself does not differentiate between these types.

If none of the built-in metric types meet your specific needs, it's easy to create your own.

Metric groups allow you to easily setup metrics which share the same name, but with different tag values. See Documentation.

Periodically a MetricsCollector instance serializes all the metrics that it is responsible for collecting. When it does so it serially calls Serialize on each metric which eventually results in a call to WriteValue. WriteValue uses an IMetricBatch to assist in writing metrics into an endpoint-defined format using an implementation of IBufferWriter<byte> for buffering purposes.

For each type of payload that can be sent to an endpoint an IBufferWriter<byte> is created that manages an underlying buffer consisting of zero or more contiguous byte arrays.

At a specific interval the MetricsCollector flushes all metrics that have been serialized into the IBufferWriter<byte> to the underlying transport implemented by an endpoint (generally an HTTP JSON API). Once flushed the associated buffer is released back to be used by the next batch of metrics being serialized.