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);
 });

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);
 });

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);
});

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

initialize(options)

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(...);