Cli Tutorial (incomplete)

What is the CLI?

The original interface to graphite, the CLI (command line interface) is a power-user interface intended to make it easy to build meaningful collections of images which serve as dashboards.

{note}The CLI currently only supports firefox, it won't work with IE. See bug #245237.

The basics

The first thing you need to know about the CLI is how to create a view (aka dashboard).

You start by making a window, drawing an image in it, making another window, etc…

Creating a window

Let's create our first window "CarbonLatency". We type in the command "create CarbonLatency" and hit enter. A new window appears.


h3. Drawing in the window

Great so we've got an empty window. Now lets draw something in it like so. Unfortunately many of the paths of graph elements are very long and hard to remember, so to aid in the process of typing it in you can use bash-style command line completion. It has some quirks but works very well overall, play around to get familiar with it.


Cool, now we've got an image in our window.

You may have noticed that we are looking at a metric (homepage views) that should always be an integer, as we don't say we had half a homepage view or anything like that. However the graph shows values in between integers, and you may wonder how that is possible. In fact it is quite common to see this in Graphite and is a frequent source of confusion. The reason this happens is because we are viewing more data points (1 day's worth of minutely data) than we have pixels to display it in, so graphite averages the values down so it can fit. So in reality each data point you seen drawn on the graph is in fact the *average minutely value for some period of time larger than a minute*. This is why we have non-integer values. To change this averaging behavior, read about the [Advanced CLI Tricks].

h3. Modifying a graph

Let's say we want to add failures to our graph of homepage hits. We can add new paths to the graph like so…


Similarly you can also say "remove _something_ from _window_". You should try removing the metric we just added for practice.

h3. Laying things out

A single image is rarely useful, the point of the CLI is to make dashboards, that is, collections of images around a common theme. So to build our dashboard we're going to make another window for looking at the latency of homepage views.

But first we should move our homepageHits window out of the way, and even better lets resize it. You can resize a window by dragging its lower right corner, just like a window on your desktop. Similarly you can move the window by clicking and dragging its title bar.


As you can see I moved the homepageHits window down and made it wider. Then I created a new homepageLatency window. Now I'm going to draw some latency metrics in it and arrange it nicely on the screen.


h3. Saving and Loading Dashboards

This dashboard is pretty simple but also pretty useful so lets save it.


Simple enough, now to see the utility of this you should try loading some other views. To see what views are available to you use the "views" command like so.


Now to use one of these views we simply enter "load _viewName_" like so


Voila, now we're looking at a different dashboard. Try and load the view you just created and see what happens.

h3. Next Steps

You've learned the basics of the CLI, but there is also [advanced guide|Advanced CLI Tricks]. Also, check out the [CLI reference|CLI Reference] for reference documentation of all the CLI commands.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License