Node Dogapi

event

create(title, text, properties, callback)

create a new event

Parameters:

title

the title of the event

text

the body of the event

properties

an optional object continaing any of the following additional optional properties

date_happened: POSIX timestamp of when it happened
priority: "normal" or "low" [defualt: "normal"]
host: the host name to associate with the event
tags: array of "tag:value"'s to associate with the event
alert_type: "error", "warning", "info" or "success" [defualt: "info"]
aggregation_key: an arbitrary string used to aggregate like events
source_type_name: options: "nagios", "hudson", "jenkins", "user", "my apps", "feed", "chef", "puppet", "git", "bitbucket", "fabric", "capistrano"

callback

function(err, res)

 var dogapi = require("dogapi");
 var options = {
   api_key: "api_key",
   app_key: "app_key"
 };
 dogapi.initialize(options);
 var title = "some new event";
 var text = "IT HAPPENED!";
 dogapi.event.create(title, text, function(err, res){
   console.dir(res);
 });
 title = "another event";
 text = "IT HAPPENED AGAIN!";
 var properties = {
   tags: ["some:tag"],
   alert_type: "error"
 };
 dogapi.event.create(title, text, properties, function(err, res){
   console.dir(res);
 });

get(eventId, callback)

get event details from the provided event id

Parameters:

eventId: the id of the event to fetch
callback: function(err, res)

 var dogapi = require("dogapi");
 var options = {
   api_key: "api_key",
   app_key: "app_key"
 };
 dogapi.initialize(options);
 dogapi.event.get(10005, function(err, res){
   console.dir(res);
 });

query(start, end, parameters, callback)

query the event stream

Parameters:

start

POSIX timestamp for start of query

end

POSIX timestamp for end of query

parameters

optional parameters to use for the query

priority: "low" or "normal"
sources: comma separated list of sources (e.g. "jenkins,user")
tags: comma separated list of tags (e.g. "tag:value1,tag:value2")

callback

function(err, res)

 var dogapi = require("dogapi");
 var options = {
   api_key: "api_key",
   app_key: "app_key"
 };
 dogapi.initialize(options);
 var now = parseInt(new Date().getTime() / 1000);
 var then = now - 3600; // an hour ago
 var parameters = {
   tags: "some:tag",
   sources: "jenkins"
 };
 dogapi.event.query(then, now, parameters, function(err, res){
   console.dir(res);
 });

infrastructure

search(query, callback)

search for metrics or hosts

Parameters:

query: the query to use for search see search docs for examples of the query (e.g. "hosts:database", "metrics:system" or "test")
callback: function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.infrastructure.search("hosts:database", function(err, res){
  console.dir(res);
});

metric

send(metric, points, extra, callback)

submit a new metric

Parameters:

metric

the metric name

points

single datapoint or array of [timestamp, datapoint], if a single point is given "now" is used as the timestamp

extra

optional, object which can contain the following keys

host: the host source of the metric
tags: array of "tag:value"'s to use for the metric
metric_type: which metric type to use ("gauge" or "counter") [default: gauge]

callback

function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.metric.send("my.metric", 1000, function(err, results){
  console.dir(results);
});
var now = parseInt(new Date().getTime() / 1000);
dogapi.metric.send("my.metric", [now, 1000], function(err, results){
  console.dir(results);
});

send_all(metrics, callback)

send a list of metrics

Parameters:

metrics

an array of metrics where each element is an object with the following keys

metric: the name of the metric
points: a single datapoint or an array of [timestamp, datapoint] (same as dogapi.metric.send)
tags: an array of "tag:value"'s
host: the source hostname to use for the metrics
metric_type: the type of metric to use ("gauge" or "counter") [default: gauge]

callback

function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
var now = parseInt(new Date().getTime() / 1000);
var metrics = [
  {
    metric: "my.metric",
    points: [now, 1000],
    tags: ["tag:value"]
  },
  {
    metric: "another.metric",
    points: 1000
  }
];
dogapi.metric.send_all(metrics, function(err, results){
  console.dir(results);
});

query(from, to, query, callback)

make a metric query

Parameters:

from: POSIX timestamp for start of query
to: POSIX timestamp for end of query
query: the string query to perform (e.g. "system.cpu.idle{*}by{host}")
callback: function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
var now = parseInt(new Date().getTime() / 1000);
var then = now - 3600; // one hour ago
var query = "system.cpu.idle{*}by{host}";
dogapi.metric.query(then, now, query, function(err, res){
  console.dir(res);
});

serviceCheck

check

check(check, hostName, status, parameters, callback)

post an update to a service check

Parameters:

check

the check name (e.g. "app.ok")

hostName

the name of the host submitting the check

status

one of dogapi.OK, dogapi.WARNING, dogapi.CRITICAL or dogapi.UNKNOWN

parameters

optional, an object containing any of the following

timestamp: POSIX timestamp for when the check happened
message: string message to accompany the check
tags: an array of "tag:value"'s associated with the check

callback

function(err, res)

 var dogapi = require("dogapi");
 var options = {
   api_key: "api_key",
   app_key: "app_key"
 };
 dogapi.initialize(options);
 var check = "app.ok";
 var hostName = "some.machine";
 dogapi.serviceCheck.check(
   check, hostName, dogapi.WARNING, function(err, res){
     console.dir(res);
 });

tag

get_all(source, callback)

get all host tags

Parameters:

source: optional, only show tags for a particular source [default: null]
callback: function callback(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.tag.get_all(function(err, results){
  console.dir(results);
});

get(hostname, options, callback)

get the host tags for a provided host name or host id

Parameters:

hostname

the hostname or host id

options

optional, an object of options for the query allowing the following

source: the source of the tags (e.g. chef, puppet, users, etc) [default: null]
by_source: whether or not to group the results by source [default: false]

callback

function callback(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.tag.get("host.name", function(err, results){
  console.dir(results);
});

create(hostname, tags, source, callback)

assign new host tags to the provided host name or host id

Parameters:

hostname: the hostname or host id
tags: list of <tag>:<value> tags to assign to the server
source: optional, the source of the tags (e.g. chef, puppet, etc) [default: users]
callback: function callback(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.tag.create("host.name", ["role:webserver"], function(err, results){
  console.dir(results);
});

update(hostname, tags, source, callback)

update the host tags for the provided host name or host id

Parameters:

hostname: the hostname or host id
tags: list of <tag>:<value> tags to assign to the server
source: optional, the source of the tags (e.g. chef, puppet, etc) [default: users]
callback: function callback(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.tag.update("host.name", function(err, results){
  console.dir(results);
});

delete_tags(hostname, source, callback)

delete the host tags for the provided host name or host id

Parameters:

hostname: the hostname or host id
source: optional, the source of the tags (e.g. chef, puppet, etc) [default: users]
callback: function callback(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.tag.delete("host.name", function(err, results){
  console.dir(results);
});

user

invite

invite(emails, callback)

invite users via e-mail

Parameters:

emails: an array of email addresses to send invites to
callback: function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
var emails = ["me@domain.com", "you@domain.com"];
dogapi.user.invite(emails, fuction(err, res){
  console.dir(res):
});

client()

the constructor for client object

See client.request

request(method, path, params, callback)

used to make a raw request to the datadog api

Parameters:

method: http method GET, POST, PUT, DELETE
path: the api url path e.g. /tags/hosts
params: an object which allows the keys query or body
callback: function to call on success/failure callback(err, result)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.client.request("GET", "/url/path", {}, function(err, results){
  console.dir(results);
});

dogapi

initialize
now

initialize(options)

configure the dogapi client with your app/api keys

Parameters:

options

An object which allows you to override the default set parameters for interacting with the datadog api. The available options are.

api_key: your api key
app_key: your app key
api_version: the version of the api [default: v1]
api_host: the host to call [default: api.datadoghq.com]

var dogapi = require("dogapi");
var options = {
  api_key: "<API_KEY_HERE>",
  app_key: "<APP_KEY_HERE>"
};
dogapi.initialize(options);
dogapi.event.create(...);

now()

get the current POSIX timestamp

var dogapi = require("dogapi");
dogapi.now();
// this is the same as
parseInt(new Date().getTime() / 1000);