Crate prima_datadog

This is an opinionated library to share code and approach to Datadog logging in prima.it

Getting started

You need to call Datadog::init in your main binary, and to do so you’ll need as argument a type that implements the Configuration trait. If you never call Datadog::init in your binary NO metrics will be sent.

Inside the configuration you’ll find an implementation of this trait tailored for prima.it needs.

use prima_datadog::{*, configuration::Configuration};

// initializes the Configuration struct
let configuration = Configuration::new(
    "0.0.0.0:1234", // to address
    "namespace", // namespace for all metrics
);

// Initializes a Datadog instance
Datadog::init(configuration).unwrap();

Then you can use the macros exposed at the base level of the module. All macros accepts

• a string value or a path to a type that implements AsRef<str> as first argument.
• zero or more arguments, separated by comma ,, for the metrics that needs more data. For example count! and timing! accepts a number while service_check! accepts a ServiceStatus and a ServiceCheckOptions
• a list of tags (which is separated from the rest of the arguments by semicolon ;) in the form of "name" => "value"

incr!("test");
decr!("test"; "some" => "data");
count!("test", 20);
count!("test", 10; "some" => "data");
time!("test", || { println!("expensive computation");});
time!("test", || { println!("expensive computation");}; "some" => "data");
timing!("test", 20; "some" => "data");
gauge!("test", "gauge value"; "some" => "data");
histogram!("test", "histogram value"; "some" => "data");
distribution!("test", "distribution value"; "some" => "data");
set!("test", "set value"; "some" => "data");
service_check!("test", ServiceStatus::OK);
service_check!("test", ServiceStatus::OK, ServiceCheckOptions::default());
event!("test", "test event"; "some" => "data");

This is an example of a custom metric, in this case based on an enum type, but it can really be whatever you want, as long as it implements AsRef<str>.

enum Metric {
    John,
    Paul,
    George,
    Ringo,
}

impl AsRef<str> for Metric {
    fn as_ref(&self) -> &str {
        match self {
            Metric::John => "john",
            Metric::Paul => "paul",
            Metric::George => "george",
            Metric::Ringo => "ringo",
        }
    }
}

// now you can do
incr!(Metric::John; "play" => "guitar");
incr!(Metric::Paul; "play" => "bass");
incr!(Metric::George; "play" => "sitar");
incr!(Metric::Ringo; "play" => "drums");

Note - Avoid high tag cardinality!

It’s important to avoid passing a large number of values for a given tag, as Datadog tracks each unique combination of tag values as a separate metric, which can significantly impact billing. For example, avoid passing things like user IDs, session IDs, request IDs, or other values that vary significantly. See https://docs.datadoghq.com/getting_started/tagging/ for more information.

Users may configure some actions to be taken when a metric cardinality threshold is exceeded. See TagTrackerConfiguration for more information.

References

• Datadog docs
• Getting started with Datadog tags

Re-exports

• pub use tracker::*;

Modules

• configuration
  Configuration module
• error
  Error module for this crate
• timing_guard
• tracker

Macros

• async_time
  Time a block of code (reports in ms) NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• compare
  Run an experiment comparing the execution time of two blocks of code Example:
• count
  Make an arbitrary change to a StatsD counter NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• decr
  Decrement a StatsD counter NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• distribution
  Report a value in a distribution NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• event
  Send a custom event as a title and a body NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• gauge
  Report an arbitrary value as a gauge NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• histogram
  Report a value in a histogram NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• incr
  Increment a StatsD counter NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• service_check
  Report the status of a service NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• set
  Report a value in a set NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• time
  Time a block of code (reports in ms) NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!
• timing
  Send your own timing metric in milliseconds NOTE: Try to minimise variation in tag values (avoid things like timestamps or ids). See note in lib docs!

Structs

• Datadog
  The Datadog type is the main entry point for the library
• ServiceCheckOptions
  Struct for adding optional pieces to a service check

Enums

• ServiceStatus
  Represents the different states a service can be in

Constants

• EMPTY_TAGS
  Helper constant for passing no tags to a metric.

Traits

• DogstatsdClient
  This trait represent a client that is able to interact with the datadog statsd collector. Its main use in this library is having a common interface for the underlying implementation, and being able to mock it for testing purposes
• TagsProvider
  Types that can provide an iterator of tags for a metric.