The easiest way to get your custom application metrics into Datadog is to send them to DogStatsD, a metrics aggregation service bundled with the Datadog Agent. DogStatsD implements the StatsD protocol and adds a few Datadog-specific extensions:
Any compliant StatsD client will work, but you won’t be able to use the Datadog-specific extensions.
Note: DogStatsD does NOT implement the following from StatsD:
DogStatsD accepts custom metrics, events, and service Checks over UDP and periodically aggregates and forwards them to Datadog. Because it uses UDP, your application can send metrics to DogStatsD and resume its work without waiting for a response. If DogStatsD ever becomes unavailable, your application won’t skip a beat.
As it receives data, DogStatsD aggregates multiple data points for each unique metric into a single data point over a period of time called the flush interval. Consider the following example, wherein DogStatsD is instructed to increment a counter each time a given database query is called:
def query_my_database(): dog.increment('database.query.count') # Run the query ...
If this function executes one hundred times during a flush interval (ten seconds, by default), it sends DogStatsD one hundred UDP packets that say “increment the counter
database.query.count”. DogStatsD aggregates these points into a single metric value (100, in this case) and sends it to Datadog where it is stored and available for graphing alongside the rest of your metrics.
First, edit your
datadog.yaml file to uncomment the following lines:
use_dogstatsd: true ... dogstatsd_port: 8125
Then restart your Agent.
By default, DogStatsD listens on UDP port 8125. If you need to change this, configure the
dogstatsd_port option in the main Agent configuration file, and restart the client. You can also configure DogStatsD to use a Unix Domain Socket.
There are DogStatsD client libraries for many languages and environments. You can use any generic StatsD client to send metrics to DogStatsD, but you won’t be able to use any of the Datadog-specific features mentioned above.
$ pip install datadog
$ gem install dogstatsd-ruby
And import it, so it’s ready to use:
from datadog import statsd
# Import the library require 'datadog/statsd' # Create a DogStatsD client instance. statsd = Datadog::Statsd.new
DogStatsD and StatsD are broadly similar, however, DogStatsD implements some things differently, and contains advanced features which are specific to Datadog. See the data types and tags section to learn more about the Datadog-specific extensions to DogStatsD, including available data types, events, service Checks, and tags.
If you’re interested in learning more about the datagram format used by DogStatsD, or want to develop your own Datadog library, see the datagram and shell usage section, which also explains how to send metrics and events straight from the command line.
Additional helpful documentation, links, and articles: