Public Repository

Last pushed: 2 years ago
Short Description
Datadog agent check for JSON endpoints
Full Description

Datadog agent check for JSON endpoints

A custom Datadog agent check that consumes JSON an HTTP GET endpoint. The JSON payload must conform
to a specific format. For use with Docker, most likely in a local development environment.



Step 1. Add a metrics enpoint to you app that exposes JSON that looks like this...

  "gauge": {
    "my.gauge": {
      "value": 3834,
      "tags": [

Step 2. Configure the check by creating a file conf.d/json.yaml with the contents


  - url: 'http://app/metrics'

Step 3. Copy conf.d/json.yaml into the container's /conf.d directory, for example by using
docker-compose and a docker-compose.yml file that looks like this...

version: '2'
    image: 'atlassianlabs/dd-agentcheck-json'
    hostname: 'dev-dd-agent'
    env_file: 'dogstatsd.env' # Sandbox API_KEY
      - 'TAGS=app:myapp,environment:development'
      - './conf.d:/conf.d'
      - 'app'
    build: '.'
        - '8080:80'

Step 3. View your metrics in Datadog...

Note: host is set automatically.

JSON payload format

The format of the JSON payload expected as a response to GET requests on your metrics URL is
inspired by the methods on Datadog's
AgentCheck class which
serves as the base class for custom agent checks.

A quick overview of the method signatures...

count           (metric, value=0,  tags=None, hostname=None, device_name=None)
decrement       (metric, value=-1, tags=None, hostname=None, device_name=None)
gauge           (metric, value,    tags=None, hostname=None, device_name=None, timestamp=None)
histogram       (metric, value,    tags=None, hostname=None, device_name=None)
increment       (metric, value=1,  tags=None, hostname=None, device_name=None)
monotonic_count (metric, value=0,  tags=None, hostname=None, device_name=None)
rate            (metric, value,    tags=None, hostname=None, device_name=None)

Note: gauge will probably be the most popular method implemented by app metrics endpoints.
Counters and histograms (timings, etc) are generally better tracked using dogstatsd from
within your app, instead of polling using this agent check service. Gauges represent
measuring the level of something at a given point in time. An example is the row count of a
database table. These are a better fit for polling using a Datadog agent check.

All of these methods take the following arguments:

  • metric: The name of the metric
  • value: The value for the metric (defaults to 1 on increment, -1 on decrement)
  • tags: (optional) A list of tags to associate with this metric.
  • hostname: (optional) A hostname to associate with this metric. Defaults to the current host.
  • device_name: (optional) A device name to associate with this metric.

Note: hostname will be filled in automatically by the http_json check using the hostname from
the registered URL.

Note: device_name will most likely not apply to the custom app metrics registered with this

You can form any number of metrics in your JSON payload using the method definitions from above. For
another example if you want two histogram metrics and one incremented counter...

  "histogram": {
    "my.histogram.metric": {
      "value": 12,
      "tags": [
    "my.other.histogram.metric": {
      "value": 3413
  "increment": {
    "my.incremented.counter": {


Docker Pull Command