Telegraf-rust is a lightweight client library for general metrics writing using Telegraf. Telegraf is a micro-service provided by InfluxData for making metrics reporting easy for distributed services - see their docs for more information.
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.
Add it to your Cargo.toml:
[dependencies]
telegraf = "*"
Using this library assumes you have a socket listener setup in your Telegraf configuration file. An example TCP connection looks like so:
[[inputs.socket_listener]]
service_address = "tcp://localhost:8094"
All usage will start by creating a socket connection via a Client
. This supports multiple connection protocols - which one you use will be determined by how your Telegraf input.socket_listener
configuration is setup. Telegraf-rust supports both TCP
and UDP
socket connections.
Once a client is setup there are multiple different ways to write points:
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" };
client.write(&point);
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,
}
As with any Telegraf point, tags are optional but at least one field is required.
use telegraf::*;
let mut client = Client::new("tcp://localhost:8094").unwrap();
let p = point!("measurement", ("tag1", "tag1Val"), ("field1", "val") ("field2", 10));
client.write_point(&p);
The macro syntax is the following format:
(<measurement>, [(<tagName>, <tagVal>)], [(<fieldName>, <fieldVal>)])
Measurement name, tag set, and field set are comma separated. Tag and field tuples are space separated. The tag set is optional.
use telegraf::{Client, Point};
let 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!"))
]
);
c.write_point(p)
Any attribute that will be the value of a field must implement the IntoFieldData
trait provided by this library.
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.