Node Dogapi

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

search for metrics or hosts

Parameters:

query

the query to use for search see datadog 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);
});

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

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

create a new monitor

Parameters:

type

one of "metric alert" or "service check"

query

the monitor query to use, you probably want to read datadog's monitor create docs

properties

optional, an object containing any of the following

• name: the name of the monitor
• message: the message for the monitor
• options: an object, to see available options please see the monitor create docs

callback

function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
var metricType = "metric alert";
var query = "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100";
dogapi.monitor.create(metricType, query, function(err, res){
  console.dir(res);
});

get an existing monitor's details

Parameters:

monitorId

the id of the monitor

groupStates

an array containing any of the following "all", "alert", "warn", or "no data"

callback

function(err, res)

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

get all monitors

Parameters:

options

optional, an object containing any of the following

• group_states: an array containing any of the following "all", "alert", "warn", or "no data"
• tags: an array of "tag:value"'s to filter on

callback

function(err, res)

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

update a monitor's details

Parameters:

monitorId

the id of the monitor to edit

query

the query that the monitor should have, see the monitor create docs for more info

properties

optional, an object containing any of the following

• name: the name of the monitor
• message: the message for the monitor
• options: an object, to see available options please see the monitor create docs

callback

function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
var query = "avg(last_1h):sum:system.net.bytes_rcvd{host:host0} > 100";
dogapi.monitor.update(1234, query, function(err, res){
  console.dir(res);
});

delete an existing monitor

Parameters:

monitorId

the id of the monitor to remove

callback

function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.monitor.remove(1234, function(err, res){
  console.dir(res);
});

mute an existing monitor

Parameters:

monitorId

the id of the monitor to mute

options

optional, an object containing any of the following

• scope: the scope to mute (e.g. "role:db")
• end: POSIX timestamp indicating when the mute should end

callback

function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.monitor.mute(1234, function(err, res){
  console.dir(res);
});

mute all monitors

Parameters:

callback

function(err, res)

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

unmute an existing monitor

Parameters:

monitorId

the id of the monitor to unmute

scope

optional, a scope to apply the unmute to (e.g. "role:db")

callback

function(err, res)

var dogapi = require("dogapi");
var options = {
  api_key: "api_key",
  app_key: "app_key"
};
dogapi.initialize(options);
dogapi.monitor.unmute(1234, function(err, res){
  console.dir(res);
});

unmute all monitors

Parameters:

callback

function(err, res)

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

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

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.getAll(function(err, results){
  console.dir(results);
});

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

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 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 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.remove("host.name", function(err, results){
  console.dir(results);
});

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

the constructor for client object

See client.request

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

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

get the current POSIX timestamp

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