Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/maxmindlin/telegraf-rust
Lightweight client library for the telegraf/influxdb protocol
https://github.com/maxmindlin/telegraf-rust
databases influxdata influxdata-telegraf influxdb metrics rust telegraf
Last synced: 2 days ago
JSON representation
Lightweight client library for the telegraf/influxdb protocol
- Host: GitHub
- URL: https://github.com/maxmindlin/telegraf-rust
- Owner: maxmindlin
- License: mit
- Created: 2020-03-01T01:28:54.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-09-01T00:29:20.000Z (about 1 year ago)
- Last Synced: 2024-09-26T01:34:52.731Z (7 days ago)
- Topics: databases, influxdata, influxdata-telegraf, influxdb, metrics, rust, telegraf
- Language: Rust
- Homepage: https://crates.io/crates/telegraf
- Size: 27.2 MB
- Stars: 15
- Watchers: 2
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Telegraf-rust
[](https://crates.io/crates/telegraf)
[](https://crates.io/crates/telegraf)
[](https://docs.rs/telegraf)
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](https://docs.influxdata.com/telegraf/v1.13/introduction/installation/) 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.
Telegraf-rust supports all socket connection types, such as UDS (unix domain socket):
- TCP (`tcp://`)
- UDP (`udp://`)
- UDS Stream (`unix://`)
- UDS Datagram (`unixgram://`)
# Install
Add it to your Cargo.toml:
```toml
[dependencies]
telegraf = "*"
```
# How to use
Using this library assumes you have a socket listener setup in your Telegraf configuration file. An example TCP connection looks like so:
```toml
[[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.
Once a client is setup there are multiple different ways to write points:
## Define structs that represent metrics using the derive macro
```rust
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:
```rust
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.
Timestamps are optional and can be set via the `timestamp` attribute:
```rust
use telegraf::*;
#[derive(Metric)]
struct MyMetric {
#[telegraf(timestamp)]
ts: u64,
field1: i32,
}
```
## Use the `point` macro to do ad-hoc metrics
```rust
use telegraf::*;
let mut client = Client::new("tcp://localhost:8094").unwrap();
let p = point!("measurement", ("tag1", "tag1Val"), ("field1", "val") ("field2", 10); 100);
client.write_point(&p);
```
The macro syntax is the following format:
```
(, [(, )], [(, )]; )
```
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 `Point` initialization
```rust
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!"))
],
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.
```rust
pub trait IntoFieldData {
fn 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 optional. 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` trait for the field type, if the implementation is not already present:
```rust
use telegraf::*;
#[derive(Copy, Clone)]
struct MyType {
// ...
}
impl From 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](https://docs.influxdata.com/influxdb/v1.8/write_protocols/line_protocol_tutorial/#timestamp).