Drew Werner

A few of us at Datadog are big fans of Emacs, the flagship text editor of the GNU project. Emacs is renowned for its flexibility and hosts a full-featured Lisp) implementation that allows the enthusiast to radically customize his or her work environment.

As many of our users know, Datadog has an extensive API that allows a range of client requests. Inspired by an excellent talk by Kris Jenkins, I thought it would be interesting to implement some of the Datadog API within Emacs, so I could do things like quickly browse a dash or query a metric without leaving the comfort of my favorite text editor.

The result is something I call datadog.el, a tool for displaying simple metric graphs within Emacs.

Set up your Datadog Emacs client

Installation instructions for the client can be found in our datadog.el project on GitHub.

Once you’ve installed datadog.el, you can open a Datadog browser with M-x datadog. You may wish to alias a key to the browser. To do this with the Datadog mnemonically-appropriate C-c d d, add the following to your initialization code:

(global-set-key (kbd "C-c d d") 'datadog)

You can find the browser in the datadog buffer and issue metric queries or browse a dashboard.

The first time you try to issue a request from Datadog, it will prompt you for your API and application keys. Once you’ve entered your keys, datadog.el will persist these credentials for you locally in ~/.emacs.d/dogapi-credentials.

Load a dashboard or graph

Browsing to a dashboard is simple and quick. Once you’re in the browser, press capital D to look at a list of dashboards, which you can interactively search using the Helm interface:

Selecting a dashboard brings up a list of tiles for that dash’s graphs:

When looking at a dash, you can also switch tiles by pressing capital T.

Once you’ve selected a tile, you’re able to navigate between graphs in the dash.

What you will see

Viewing timeseries data in the terminal is a somewhat different experience than using a modern graphical interface. For simplicity’s sake, we are not supporting our heatmaps, distributions, or top lists. Also, due to the low resolution and limited graphical expressivity of a text display, stacking multiple series on top each other or overlaying multiple series is impractical. Instead, what you will see looks something like this:

You can analyze your Datadog graphs with these Emacs commands:

• Move the time cursor by steps with f (forward) and b (backward) or in larger jumps with capital F and B.

• Set the time frame to one of four options: one hour (1), four hours (4), one day (d), and one week (w).

• Refresh the graph with more recent data with the r button. Note: in order to prevent someone from inadvertently sending too many API requests, we throttle refreshes at a rate that depends on the graph timeframe.

• Navigate between series with the n (next) and p (previous) keys or jump to a particular scope with the j key. This is because all charts are displayed as area graphs and all constituent series are displayed separately.

• While viewing a graph, switch to a different dash or graph by using the capital D or T commands, respectively.

You can see a summary of all these commands (plus a few others) by accessing the mode specific help from inside the datadog buffer. Mode-specific help can be accessed via M-x describe-mode or by using the shortcut C-h m.

Next steps

We hope this is a tool that some of you find fun, and maybe even useful. If you’re interested in learning more or contributing to the project, you can see the source code on GitHub. Some features that might be interesting to implement include:

• Summary of Alert Status

• Searching and Browsing Events (and comments)

• Adding Comments to an Event

And there are probably still more ideas that we haven’t yet thought of.

We’d love to get your contributions, whether in the form of feature suggestions, bug reports, or pull requests. Have fun, and let us know what you think.

Vim and Sublime fans, we’d love to see what you can offer for Datadog browsing—if you’re up for the challenge.

Finally, if you like this kind of stuff, join Datadog.