yuanrui / influxdb-csharp

A .NET library for efficiently sending points to InfluxDB

InfluxDB .NET Collector

This is a C# implementation of the InfluxDB ingestion 'Line Protocol'.

You can use it to write time series data to InfluxDB version 0.9.3+ over HTTP or HTTPS. Two packages are provided:

• A higher-level metrics-oriented API described in Getting Started below
• A bare-bones HTTP line protocol client, described in the Raw Client API section

Supporting the full/read API of InfluxDB is an explicit non-goal: this package will be kept small so as to have a minimal footprint when used in client applications.

Getting Started

Install the InfluxDB.Collector NuGet package:

Install-Package InfluxDB.Collector

Add using statements where needed:

using InfluxDB.Collector;

Configure a MetricsCollector. These can be used directly, or via the static Metrics class:

Metrics.Collector = new CollectorConfiguration()
    .Tag.With("host", Environment.GetEnvironmentVariable("COMPUTERNAME"))
    .Batch.AtInterval(TimeSpan.FromSeconds(2))
    .WriteTo.InfluxDB("http://192.168.99.100:8086", "data")
    .CreateCollector();

Send points using the methods of MetricsCollector or Metrics:

Metrics.Increment("iterations");

Metrics.Write("cpu_time",
    new Dictionary<string, object>
    {
        { "value", process.TotalProcessorTime.TotalMilliseconds },
        { "user", process.UserProcessorTime.TotalMilliseconds }
    });

Metrics.Measure("working_set", process.WorkingSet64);

View aggregated metrics in a dashboarding interface such as Grafana.

Raw Client API

The raw API is a very thin wrapper on InfluxDB's HTTP API, in the InfluxDB.LineProtocol package.

Install-Package InfluxDB.LineProtocol

To send points, create a LineProtocolPayload containing a batch of LineProtocolPoints. Each point carries the measurement name, at least one value, an optional set of tags and an optional timestamp:

var cpuTime = new LineProtocolPoint(
    "working_set",
    new Dictionary<string, object>
    {
        { "value", process.WorkingSet64 },
    },
    new Dictionary<string, string>
    {
        { "host", Environment.GetEnvironmentVariable("COMPUTERNAME") }
    },
    DateTime.UtcNow);

var payload = new LineProtocolPayload();
payload.Add(cpuTime);
// Add more points...

(If the timestamp is not specified, the InfluxDB server will assign a timestamp to each point on arrival.)

Write the points to InfluxDB, specifying the server's base URL, database name, and an optional username and password:

var client = new LineProtocolClient(new Uri("http://my-server:8086"), "data");
var influxResult = await client.WriteAsync(payload);
if (!influxResult.Success)
    Console.Error.WriteLine(influxResult.ErrorMessage);

Diagnostics

The collector will not throw exceptions when communication errors occur. To be notified of metric collection issues, register an error handler:

CollectorLog.RegisterErrorHandler((message, exception) =>
{
    Console.WriteLine($"{message}: {exception}");
});

Status

This project is still undergoing some change while in development, but the core functionality is stabilizing. See issues tagged enhancement for roadmap items. It's currently targeting .NET 4.5.1 and .NET Core using Visual Studio 2017.