Crate telegraf

source ·
Expand description

Telegraf-rust provides a lightweight client library for writing metrics to a InfluxDB Telegraf service.

This library does not provide querying or other InfluxDB client-library features. This is meant to be lightweight and simple for services to report metrics.

How to use

All usage will start by creating a socket connection via a crate::Client. This supports multiple connection protocols - which one you use will be determined by how your Telegraf input.socket_listener configuration is setup.

Once a client is setup there are multiple different ways to write points.

Define structs that represent metrics using the derive macro.

use telegraf::*;

let mut client = Client::new("tcp://localhost:8094").unwrap();

#[derive(Metric)]
struct MyMetric {
    field1: i32,
    #[telegraf(tag)]
    tag1: String,
}

let point = MyMetric { field1: 1, tag1: "tag".to_owned() };
client.write(&point);

As with any Telegraf point, tags are optional but at least one field is required.

By default the measurement name will be the same as the struct. You can override this via derive attributes:

use telegraf::*;

#[derive(Metric)]
#[measurement = "custom_name"]
struct MyMetric {
    field1: i32,
}

Timestamps are optional and can be set via the timestamp attribute:

use telegraf::*;

#[derive(Metric)]
struct MyMetric {
    #[telegraf(timestamp)]
    ts: u64,
    field1: i32,
}

Use the crate::point macro to do ad-hoc metrics.

use telegraf::*;

let mut client = Client::new("tcp://localhost:8094").unwrap();

let p = point!("measurement", ("tag1", "tag1Val"), ("field1", "field1Val"));
client.write_point(&p);

The macro syntax is the following format:

(<measurement>, [(<tagName>, <tagVal>)], [(<fieldName>, <fieldVal>)]; <timestamp>)

Measurement name, tag set, and field set are comma separated. Tag and field tuples are space separated. Timestamp is semicolon separated. The tag set and timestamp are optional.

Manual crate::Point initialization.

use telegraf::{Client, Point};

let mut c = Client::new("tcp://localhost:8094").unwrap();

let p = Point::new(
    String::from("measurement"),
    vec![
        (String::from("tag1"), String::from("tag1value"))
    ],
    vec![
        (String::from("field1"), Box::new(10)),
        (String::from("field2"), Box::new(20.5)),
        (String::from("field3"), Box::new("anything!"))
    ],
    Some(100),
);

c.write_point(&p);

Field Data

Any attribute that will be the value of a field must implement the IntoFieldData trait provided by this library.

use telegraf::FieldData;

pub trait IntoFieldData {
    fn into_field_data(&self) -> FieldData;
}

Out of the box implementations are provided for many common data types, but manual implementation is possible for other data types.

Timestamps

Timestamps are an optional filed, if not present the Telegraf daemon will set the timestamp using the current time. Timestamps are specified in nanosecond-precision Unix time, therefore u64 must implement the From<T> trait for the field type, if the implementation is not already present:

use telegraf::*;

#[derive(Copy, Clone)]
struct MyType {
    // ...
}

impl From<MyType> for u64 {
    fn from(my_type: MyType) -> Self {
        todo!()
    }
}

#[derive(Metric)]
struct MyMetric {
    #[telegraf(timestamp)]
    ts: MyType,
    field1: i32,
}

More information about timestamps can be found here.

Re-exports

Modules

Macros

Structs

  • Client
    Connection client used to handle socket connection management and writing.
  • Point
    A single influx metric. Handles conversion from Rust types to influx lineprotocol syntax.

Enums

Traits

Type Definitions

  • TelegrafResult
    Common result type. Only meaningful response is an error.

Derive Macros