mcasper / dogstatsd-rs Goto Github PK

A Dogstatsd Client for Rust

License: MIT License

Rust 100.00%

dogstatsd-rs's Introduction

dogstatsd-rs

A Rust client for interacting with Dogstatsd

Dogstatsd is a custom StatsD implementation by DataDog for sending metrics and events to their system. Through this client you can report any type of metric you want, tag it, and enjoy your custom metrics.

Full Documentation

Usage

Build an options struct and create a client:

use dogstatsd::{Client, Options};

// Binds to a udp socket on an available ephemeral port on 127.0.0.1 for
// transmitting, and sends to 127.0.0.1:8125, the default dogstatsd address.
let default_options = Options::default();
let default_client = Client::new(default_options).unwrap();

// Binds to 127.0.0.1:9000 for transmitting and sends to 10.1.2.3:8125, with a
// namespace of "analytics".
let custom_options = Options::new("127.0.0.1:9000", "10.1.2.3:8125", "analytics", vec!(String::new()));
let custom_client = Client::new(custom_options).unwrap();

// You can also use the OptionsBuilder API to avoid needing to specify every option.
let built_options = OptionsBuilder::new().from_addr(String::from("127.0.0.1:9001")).build();
let built_client = Client::new(built_options).unwrap();

Start sending metrics:

use dogstatsd::{Client, Options, ServiceCheckOptions, ServiceStatus};

let client = Client::new(Options::default()).unwrap();
let tags = &["env:production"];

// Increment a counter
client.incr("my_counter", tags).unwrap();

// Decrement a counter
client.decr("my_counter", tags).unwrap();

// Time a block of code (reports in ms)
client.time("my_time", tags, || {
    // Some time consuming code
}).unwrap();

// Report your own timing in ms
client.timing("my_timing", 500, tags).unwrap();

// Report an arbitrary value (a gauge)
client.gauge("my_gauge", "12345", tags).unwrap();

// Report a sample of a histogram
client.histogram("my_histogram", "67890", tags).unwrap();

// Report a sample of a distribution
client.distribution("distribution", "67890", tags).unwrap();

// Report a member of a set
client.set("my_set", "13579", tags).unwrap();

// Report a service check
let service_check_options = ServiceCheckOptions {
  hostname: Some("my-host.localhost"),
  ..Default::default()
};
client.service_check("redis.can_connect", ServiceStatus::OK, tags, Some(service_check_options)).unwrap();

// Send a custom event
client.event("My Custom Event Title", "My Custom Event Body", tags).unwrap();

Benchmarks

Support is provided for running benchmarks of all client commands. Until the Bencher type is stable Rust, the benchmarks are isolated behind the unstable feature flag. To run the benchmarks using rustup:

rustup run nightly cargo bench --features=unstable

dogstatsd-rs's People

Contributors

Stargazers

Watchers

dogstatsd-rs's Issues

Convert public API to builder pattern

Trying to provide a clean API that has lots of optional fields is pretty verbose right now, as was made clear by service checks, not to mention all the options that events support that we should add. My thought is to transition the API to more of a builder pattern, so that you never have to specify the optional arguments that you don't care about:

client.service_check("redis.can_connect", ServiceStatus::OK)
    .hostname("my-host.localhost")
    .timestamp(1510327616)
    .send()

client.gauge("my_gauge", "12345")
    .tag("special:tag")
    .send()

Add service checks

Looks like this is a metric I overlooked in the initial implementation, mostly because the ruby library seems to also forget about it.

https://docs.datadoghq.com/guides/dogstatsd/#service-checks

Add metric batching

Might be nice to offer a batch block, so that multiple metrics that are sent together frequently can be batched into one packet

Support for async function in `time` function

Would be cool to be able to track duration of async functions too in time function. What i imagine is something like:

  use dogstatsd::{Client, Options};
  use std::thread;
  use std::time::Duration;

  let client = Client::new(Options::default()).unwrap();
  client
    .time("timer", &["tag:time"], || async {
      thread::sleep(Duration::from_millis(200))
    })
    .await
    .unwrap_or_else(|e| println!("Encountered error: {}", e))

Thank you in advance

Full support for each metric type's options

Options like sample_rate, hostname, timestamp, etc. We have a lot of missing options

DataDog Configuration not documented

Hi all, maybe a dumb question, but let's ask anyway :D

We've got some Rust Lambda's running and we want to add custom metrics, this library looks great, but I'm wondering what the approach if for configuring DataDog (API key etc).

Is there any example for that?

`Client` `timing` function should accept `u128` instead of `i64`

Since a duration of an execution is supposed to be greater than 0 i think that it might be better, in timing function (and in TimingMetric struct too), to use an u128 instead of i64.

Moreover i'm not sure about this comment (Send your own timing metric in milliseconds). Maybe i'm wrong, but in datadog documentation is written that duration metrics are reported as microseconds.

Thank you in advance and for the library :). We use it really a lot!

Rather than implement a inherent method named default, have Options implement the Default type

this allows for more flexible usage and you get the Options::default() method for free

This also allows for more flexible custom construction

let ops = Options {
  to_addr: "host",
 ..Default::default()
};

Use String instead of &'static str for ServiceCheckOptions fields

The need to use &'static str as the message type for ServiceCheckOptions is very restrictive. Is there any clear reason you need the static lifetime? Could you instead make do with an owned String?

Documentation is out of date

The examples in the readme don't work in version 0.6.1.
If I create a new project and copy the example code:

use dogstatsd::{Client, Options};

fn main() {
    let client = Client::new(Options::default());

    // Increment a counter
    client.incr("my_counter", vec![]).unwrap();
}

I get a compiler error:

Compiling rust-test v0.1.0 (/Users/duncanuszkay/src/github.com/Shopify/rust-test)
error[E0599]: no method named `incr` found for type `std::result::Result<dogstatsd::Client, dogstatsd::error::DogstatsdError>` in the current scope
 --> src/main.rs:7:12
  |
7 |     client.incr("my_counter", vec![]).unwrap();
  |            ^^^^

error: aborting due to previous error

It seems that this is due to the fact that the Client::new method returns a result in the newer code.

Additionally the link to full documentation is out of date:

New release request

Hello @mcasper can i ask you to create a new release? Thank you in advance

async/await

I'm working on an async networking service that will need to emit metrics, soon. After looking at the existing crates available, dogstatsd is one of my top choices. Unfortunately for me, none of the existing crates support async/await. But fortunately for you, I will be able to dedicate some company time to implement this.

Before I begin any work or submit any PRs, I'd like to start a conversation to work out the details. Has there been any brainstorming on what the API might look like, or are there any immediate plans to begin work on async/await? Would you be happy with a feature gate to transform the public API into an async interface, or would you prefer a separate collection of structs? Or maybe even a separate crate altogether?

The code as-is seems like it would lend itself pretty nicely to the former; a feature gate. One challenge I can spot right away is that the Client struct assumes it will be responsible for creating the socket (tightly coupling it with the socket impl in std). This is easy to change to a type that is generic over anything that implements Read + Write (or AsyncRead + AsyncWrite).

This work will probably fall on my plate in early January. Let me know if you are interested in collaborating, and what (if anything) may have already been done.