A .NET client to send metrics to Bosun/OpenTSDB. http://bosun.org
C# PowerShell Batchfile
Latest commit 3e2cb64 Jun 15, 2016 @bretcope v3.0.1

README.md

BosunReporter.NET

NuGet version Build status

A thread-safe C# .NET client for reporting metrics to Bosun (Time Series Alerting Framework). This library is more than a simple wrapper around the JSON API. 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 3.0

Basic Usage

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()
{
    MetricsNamePrefix = "app_name.",
    BosunUrl = "http://bosun.mydomain.com:8070",
    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.

Create a counter with only the default tags:

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

Increment the counter by 1:

counter.Increment();

Using Tags

Tags are used to subdivide data in Bosun/OpenTSDB. 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.

Metric Types

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.

Name Description
Counter A general-purpose manually incremented long-integer counter.
SnapshotCounter Calls a user-provided Func<long?> to get the current counter value each time metrics are going to be posted to the Bosun API.
ExternalCounter A persistent counter (no resets) for very low-volume events.

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.NET 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.

Name Description
SnapshotGauge Similar to a SnapshotCounter, it calls a user provided Func<double?> to get the current gauge value each time metrics are going to be posted to the Bosun API.
EventGauge Every data point is sent to Bosun. Good for low-volume events.
AggregateGauge Aggregates data points (min, max, avg, median, etc) before sending them to Bosun. Good for recording high-volume events.
SamplingGauge Record as often as you want, but only the last value recorded before the reporting interval is sent to Bosun (it samples the current value).

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

Metric Groups

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