DogFood
A C++, header only library for DataDog communication on Windows, Mac, and Linux
Install / Use
/learn @garrettsickles/DogFoodREADME
DogFood
(See us on DataDog's developer site)
A C++ API for reporting DataDog metrics
- Header Only
- Stateless
- Cross Platform
- UDP and UDS (linux only) communication with DogStatsD agent
Simple Example
Running the barebones example program in example/simple_example.cpp produces the following:
Before You Start
This project is used for communicating with a DataDog Agent
If you do not have a DataDog Agent installed, please install it and connect it to your account!
Configuration
UDP - User Datagram Protocol (Custom)
Configure DogFood to send metrics to a custom host and port over UDP
Here is an example in example/simple_example_udp.cpp
DogFood::Send(DogFood::Metric(
"DogFood.MetricTest",
49.5555,
DogFood::Counter,
0.75,
DogFood::Tags({ { "f", "9" }, { "g", "8" } })
), DogFood::UDP("127.0.0.1", 8125));
UDS - Unix Domain Sockets (Custom)
Configure DogFood to send metrics to a custom host and port over UDP
Here is an example in example/simple_example_linux_uds.cpp
DogFood::Send(DogFood::Metric(
"DogFood.MetricTest",
49.5555,
DogFood::Counter,
0.75,
DogFood::Tags({ { "f", "9" }, { "g", "8" } })
), DogFood::UDS("/var/run/datadog/dsd.socket"));
Note:
- Set datadog agent to use UDS
- In
/etc/datadog-agent/datadog.yaml, setdogstatsd_socketto/var/run/datadog/dsd.socket- e.g. -
dogstatsd_socket: /var/run/datadog/dsd.socket
- e.g. -
- In
- Add permissions for dd-agent
$ mkdir /var/run/datadog/$ sudo chown dd-agent:dd-agent -R /var/run/datadog/
UDP - User Datagram Protocol (At build time)
Configure DogFood to send metrics to a custom host and port over UDP
Here is an example in example/simple_example.cpp
// At compile time override the default host & default port
// (Please do not compile with 255.255.255.255)
g++ (...) -DDOGSTATSD_HOST="255.255.255.255" -DDOGSTATSD_PORT=12345
// At compile time in the source
#define DOGSTATSD_HOST "127.0.0.1"
#define DOGSTATSD_PORT 8125
// By default will send over UDP to DOGSTATSD_HOST:DOGSTATSD_PORT
DogFood::Send(DogFood::Metric(
"DogFood.MetricTest",
49.5555,
DogFood::Counter,
0.75,
DogFood::Tags({ { "f", "9" }, { "g", "8" } })
));
Example
// Only need to include this file
// No linkage needed
#include <DogFood/DogFood.h>
// ...std::this_thread::sleep_for
#include <thread>
int main()
{
// Metrics Forever
while (true) {
// Report a 'metric'
// - Named "DogFood.MetricTest"
// - Value of 49.5555
// - Type of Counter
// - Sampled rate of 75%
// - Tags of f="9" and g="8"
DogFood::Send(DogFood::Metric(
"DogFood.MetricTest",
49.5555,
DogFood::Counter,
0.75,
DogFood::Tags({ { "f", "9" }, { "g", "8" } })
));
// Report an 'event'
// - Named "DogFood Event"
// - Message of "The event was invoked"
// - At a the current time
DogFood::Send(DogFood::Event(
"DogFood Event",
"The event was invoked",
time(NULL)
));
// Report a 'service_check'
// - Named "DogFood Service Check"
// - Level of Warning
// - At a the current time
DogFood::Send(DogFood::ServiceCheck(
"DogFood Service Check",
DogFood::Status::Warning,
time(NULL)
));
// Sleep for 30 seconds
std::this_thread::sleep_for(std::chrono::seconds(30));
}
}
Metric
////////////////////////////////////////////////////////////////
// //
// 888b d888 888 d8b //
// 8888b d8888 888 Y8P //
// 88888b.d88888 888 //
// 888Y88888P888 .d88b. 888888 888d888 888 .d8888b //
// 888 Y888P 888 d8P Y8b 888 888P" 888 d88P" //
// 888 Y8P 888 88888888 888 888 888 888 //
// 888 " 888 Y8b. Y88b. 888 888 Y88b. //
// 888 888 "Y8888 "Y888 888 888 "Y8888P //
// //
////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////
// Format
//
// 'metric.name:value|type|@sample_rate|#tag1:value,tag2'
//
// - metric.name
// A string with no colons, bars, or @ characters.
// See the metric naming policy.
//
// - value
// An integer or float.
//
// - type
// 'c' for counter, 'g' for gauge, 'ms' for timer,
// 'h' for histogram, 's' for set.
//
// - @sample_rate
// (Optional)
// A float between 0 and 1, inclusive.
// Only works with counter, histogram,
// and timer metrics. Default is 1
// (i.e. sample 100% of the time).
//
// - tags
// (Optional)
// A comma separated list of tags.
// Use colons for key/value tags, i.e. env:prod.
// The key device is reserved; Datadog drops a
// user-added tag like device:foobar.
//
////////////////////////////////////////////////////////////////
// Samples
//
// # Increment the page.views counter
// 'page.views:1|c'
//
// # Record the fuel tank is half-empty
// 'fuel.level:0.5|g'
//
// # Sample the song length histogram half of the time
// 'song.length:240|h|@0.5'
//
// # Track a unique visitor to the site
// 'users.uniques:1234|s'
//
// # Increment the active users counter, tag by country
// 'users.online:1|c|#country:china'
//
// # Track active China users and use a sample rate
// 'users.online:1|c|@0.5|#country:china'
//
////////////////////////////////////////////////////////////////
// Type
//
// The 'Type' of a DataDog 'Metric'
//
enum Type {
Counter,
Gauge,
Timer,
Histogram,
Set
};
std::string Metric(
const std::string _name,
const ValueType _value,
const Type _type,
const double _rate = 1.0,
const Tags& _tags = Tags()
);
Event
////////////////////////////////////////////////////////////////
// //
// 8888888888 888 //
// 888 888 //
// 888 888 //
// 8888888 888 888 .d88b. 88888b. 888888 //
// 888 888 888 d8P Y8b 888 "88b 888 //
// 888 Y88 88P 88888888 888 888 888 //
// 888 Y8bd8P Y8b. 888 888 Y88b. //
// 8888888888 Y88P "Y8888 888 888 "Y888 //
// //
////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////
// Format
//
// '_e{title.length,text.length}:title|text|d:timestamp|
// h:hostname|p:priority|t:alert_type|#tag1,tag2'
//
// - _e
// The datagram must begin with _e
//
// - title
// Event title.
//
// - text
// Event text.
// Insert line breaks with an escaped slash (\\n)
//
// - d:timestamp
// (Optional)
// Add a timestamp to the event.
// Default is the current Unix epoch timestamp.
//
// - h:hostname
// (Optional)
// Add a hostname to the event. No default.
//
// - k:aggregation_key
// (Optional)
// Add an aggregation key to group the event with
// others that have the same key. No default.
//
// - p:priority
// (Optional)
// Set to ‘normal’ or ‘low’. Default ‘normal’.
//
// - s:source_type_name
// (Optional)
// Add a source type to the event. No default.
//
// - t:alert_type
// (Optional)
// Set to ‘error’, ‘warning’, ‘info’ or ‘success’.
// Default ‘info’.
//
// - #tag1:value1,tag2,tag3:value3...
// (Optional)
// The colon in tags is part of the tag list string
// and has no parsing purpose like for the other
// parameters. No default.
//
////////////////////////////////////////////////////////////////
// Samples
//
// # Send an exception
// '_e{21,36}:An exception occurred|Cannot parse CSV file
// from 10.0.0.17|t:warning|#err_type:bad_file'
//
// # Send an event with a newline in the text
// '_e{21,42}:An exception occurred|Cannot parse JSON
// request:\\n{"foo: "bar"}|p:low|#err_type:bad_request'
//
////////////////////////////////////////////////////////////////
// Priority
//
// The 'Priority' of a DataDog 'Event'
//
enum class Priority {
Low,
Normal
};
////////////////////////////////////////////////////////////////
// Alert
//
// The 'Alert' type of a DataDog 'Event'
//
enum class Alert {
Info,
Success,
Warning,
Erro
