How to use the Datadog Python Library to send custom metrics

3 min read | by Jordi Prats

Using the Datadog Python Library we can very easily inject metrics into Datadog. These metrics will fall into the "custom metrics" category. Let's check the python code needed to do so:

First we will have to make sure the have the datadog module installed:

pip install datadog

Once it is installed we will be able to start writing our datadog metrics sender script by importing what we are going to use:

from datadog import initialize, api

To initialize the library we will have to configure some settings such as the api_key, or depending on the setup, also the api_host. So the required code would look like this:

options = {
    'api_key': '...',
    'api_host': 'https://...',
}

initialize(**options)

The function we need to call to actually send a metric is api.Metric.send():

response = api.Metric.send(
                            metric='pet2cattle.datadog.metric',
                            points=[(int(time.time()), float(1))],
                            tags=tags,
                            type=type_metric
                          )

The metric is the name we want to use, on the example above we are using pet2cattle.datadog.metric

The points option is an array of points we want to push to datadog with it's timestamp, so if we want to push a value (1) for the timestamp 1575317847, the value we would set it to an array of tuples as follows:

[(1575317847,1)]

To get the timestamp we can convert the result we get from time.time() to a int as follows:

import time

int(time.time())

We can also especify a set of tags as a list of strings where each string contains the tag with it's value separated by a colon:

tags = ["tag:value"]

Finally, we need to tell datadog with type of data we are submitting. It can be one of the following:

  • gauge: Represents a snapshot of events in one time interval, a representative snapshot value is the last value submitted to the Agent during a time interval. We can use it to monitor something reporting continuously, for example, the available disk space

  • count: Represents the total number of event occurrences in one time interval. This number of events can accumulate or decrease over time, doesn't need to monotonically increase. It can be used to track the total number of connections made to a database

  • rate: Represents the total number of event occurrences per second in one time interval. It can be used to track how often something is happening. For example, the frequency of connections made to a database

If everything is injected correctly we will get a map as follows as a response:

{'status': 'ok'}

Otherwise the object will contain more information about what when wrong.

Putting all the code together an example python script that sends custom metrics to datadog looks like follows:

from datadog import initialize, api
import time


options = {
    'api_key': '...',
    'api_host': 'https://...',
}

initialize(**options)

response = api.Metric.send(
                            metric='pet2cattle.datadog.metric',
                            points=[(int(time.time()), float(1))],
                            tags=["tag:value"],
                            type='rate'
                          )

Posted on 16/07/2021

Categories