The Dashboard User Interface

The Dashboard interface is the tool of choice for displaying more than one graph at a time, with all graphs showing the same time range. Unless you’re using the HTTP interface to embed graphs in your own applications or web pages, this is the Graphite interface you’ll use most often. It’s certainly the interface that will be of most use to operations staff.

Getting Started with the Dashboard Interface

You can access the Dashboard interface directly at http://my.graphite.host/dashboard, or via the link at the top of the Composer interface.

Completer or browser tree?

When you open the Dashboard interface, you’ll see the top of the page taken up by a completer. This allows you to select a metric series to show on a graph in the dashboard.

If you’re only viewing a dashboard rather than modifying one, the completer just gets in the way. You can either resize it by dragging the splitter bar (between the completer and graph panels), or hide it by clicking on the little triangular icon in the splitter bar. Once hidden, the same triangular icon serves to display the panel again.

An alternative to the completer is a browser tree, which shows to the left of the graph panel. To change to this mode, use the Dashboard | Configure UI menu item, and choose Tree (left nav). You’ll have to refresh the page to get this to show. The completer and browser tree do the same job, so the choice is down to your personal preference. Your choice is recorded in a persistent browser cookie, so it should be preserved across sessions.

Creating or Modifying a Dashboard

When you open the Dashboard interface, no dashboard is open. You can either start building a new dashboard, or you can open an existing one (see Opening a Dashboard) and modify that. If you’re working on a previously-saved dashboard, its name will show at the top of the completer and browser tree panels.

Note for Power Users: Any action that can be performed via the UI, as explained in this section, can also be performed using the Edit Dashboard function (as JSON text). See Editing, Importing and Exporting via JSON.

Adding a Graph

To add a new graph directly, you select a metric series in the completer or browser tree, and a graph for that value is added to the end of the dashboard. Alternatively, if a graph for that metric series already exists on the dashboard, it will be removed.

See later for ways of customizing the graph, including adding multiple metric series, changing axes, adding titles and legends etc.

Importing a Graph

Existing graphs can be imported into your dashboard, either from URLs or from saved graphs.

Import a graph from a URL when you already have the graph you want displaying elsewhere (maybe you built it in the Completer, or you want to copy it from another dashboard). Use the Graphs | New Graph | From URL menu item and enter the URL, which you probably copied from another browser window.

Alternatively, if you’ve saved a graph in the Composer, you can import it. Use the Graphs | New Graph | From Saved Graph menu item, and select the graph to import.

Deleting a Graph

When you hover the mouse over a graph, a red cross icon appears at the top right. Click this to delete the graph from the dashboard.

Multiple Metrics - Combining Graphs

The simplest way to show more than one metric on a graph is to add each as a separate graph, and then combine the graphs. To combine 2 graphs, drag one over the other and then wait until the target graph shows “Drop to Merge”. Drop the graph, and the target graph will now show all metrics from both graphs. Repeat for as many metrics as required.

Note, however, that if you have multiple related metrics, it may be easier to use a single path containing wildcards - see Paths and wildcards.

Re-ordering Graphs

Drag a graph to the position you want, and drop it before the “Drop to Merge” message shows.

For power users wanting to perform a large scale re-ordering of graphs in a dashboard, consider using Editing, Importing and Exporting via JSON.

Saving the Dashboard

If the dashboard has previously been saved, and assuming you have any required permissions (see later), you can use the Dashboard | Save menu item to save your changes. Note that your dashboard will be visible to all users, whether logged in or not, and can be edited and/or deleted by any user with the required permissions.

You can use the Dashboard | Save As menu item to save your dashboard for the first time, or to save it with a different name.

Viewing a Dashboard

This section explains the options available when viewing an existing dashboard. Once you’ve defined the dashboards you need, you’ll spend most of your time in this mode.

Note that you’ll most likely want to hide the completer when working in this mode - see earlier.

Opening a Dashboard

Use the Dashboard | Finder menu item to select the dashboard to open.

Setting the Time Range

Graphite allows you to set a time range as relative or absolute. Relative time ranges are most commonly used. The same time range is applied to every graph on the dashboard, and the current time range is shown in the center of the menu bar.

To set a relative time range, click the Relative Time Range menu button, and enter the time range to display (value and units, e.g. “6 hours”). By default, this time range ends at the current time, as shown by “Now” in the “Until” units field. However, you can move the time range back by entering your own value and units in the “Until” fields.

To set an absolute time range, click the Absolute Time range menu button, and set the start and end dates and times (all are required). Dates can be selected using the calendar picker or entered directly in US format (mm/dd/yyyy), while times can be selected from the dropdown or entered in 12 or 24 hour format (e.g. “5:00 PM”, “17:00”).

Manual and Auto Refresh

By default, dashboards are set to manually refresh. Click the green refresh menu button to the left of the Auto-Refresh button to refresh the dashboard. The time of the last refresh is shown at the right of the menu bar.

Alternatively, set the dashboard to auto-refresh by ensuring that the Auto-Refresh menu button is pressed in. The refresh defaults to 60 seconds, but you can change this in the edit field to the right of the Auto-Refresh button.

Note that refresh options are saved with the dashboard.

Customizing Graphs

To change a graph on the dashboard, click on it. This will display a pop-up containing the following sections:

• A list of all metric elements, i.e. the path and functions for each of the data elements displayed on the graph
• An Apply Function menu button, which allows functions to be applied to the currently-selected item in the metrics list
• A Render Operations menu button, which allows customization of the graph as a whole
• A Graph Operations menu button, providing menu items for miscellaneous actions to take on the graph.

Paths and Wildcards

In any reasonably-sized environment, you’ll have the same or similar metrics being collected from a number of points. Rather than requiring you to add each one to the graph individually, Graphite provides a powerful wildcard mechanism - for example, the metric path servers.*ehssvc*.cpu.total.{user,system,iowait} will include a line on the graph for the user, system and I/O wait CPU usage for every server whose name contains ehssvc. Each of these is referred to as a metric series. Graphite also provides a large number of functions for working on groups of metric series, e.g. showing only the top 5 metric series from a group.

See Paths and Wildcards for further information.

Customizing a Single Metric Element

To customize a single metric element, you select the element in the metric list, then use the menu items on the Apply Function menu button to apply functions to the metric element. Note that each metric element in the list may include multiple metric series, e.g. if the path includes wildcards.

The functions are grouped in the menu, as follows:

Combine

Functions that combine a group of metric series (returned by a path containing wildcards) into a single series (and therefore a single line). Includes sum, average, product, minimum, maximum.

Transform

Functions that transform the values in a metric series, against either the Y-axis or (less commonly) the X-axis. Includes scale, scale to seconds, offset, derivative, integral, time-shift, log.

Calculate

Functions that calculate a new metric series based on an existing metric series. Includes moving average, percentage, Holt-Winters forecast, ratio and difference (of 2 metrics)

Filter

Functions that filter metric series from a group. Includes highest current value, current value above limit, most deviant, remove below percentile.

Special

Functions that control how the metric series are drawn on the graph. Includes line colors/widths/styles, drawing stacked, drawing on the second Y-axis, and setting the legend name either directly or from the path.

The last menu item is Remove Outer Call, which removes the outer-most function on the current metric.

Customizing the Whole Graph

The Render Options menu button is used to set options that apply to the whole graph, rather than just the selected metric.

The functions are grouped as follows:

Graph Title

Unsurprisingly, this sets the title for the graph. See title.

Display

Provides options for:

• fonts (see fontName, fontBold, fontItalic, fontSize and fgcolor)
• colors (see colorList, bgcolor, majorGridLineColor, minorGridLineColor and areaAlpha)
• legends (see hideLegend and uniqueLegend)
• line thickness (see lineWidth)
• hiding of graph elements (see graphOnly, hideAxes, hideYAxis and hideGrid)
• apply a template (see template).

Line Mode

Sets the way lines are rendered, e.g. sloped, staircase, connected, and how the value None is rendered. See lineMode and drawNullAsZero.

Area Mode

Determines whether the area below lines is filled, and whether the lines are stacked. See areaMode.

X-Axis

Allows setting the time format for dates/times on the axis (see xFormat), the timezone for interpretation of timestamps (see tz), and the threshold for point consolidation (the closest number of pixels between points before they are consolidated, see minXStep).

Y-Axis

Determines how the Y-axis or axes are rendered. This includes:

• label (see vtitle)
• minimum/maximum values on the axis (see yMin and yMax)
• the number of minor lines to draw (see minorY)
• drawing on a logarithmic scale of the specified base (see logBase)
• step between the Y-axis labels and gridlines (see yStep)
• divisor for the axis (see yDivisors)
• unit system (SI, binary, or none - see yUnitSystem)
• side the axis appears (see yAxisSide).

When you have more than one Y-axis (because you selected Apply Function | Special | Draw in second Y axis for at least one metric series), use the Dual Y-Axis Options item on this menu. This provides individual control of both the left and right Y-axes, with the same settings as listed above.

Other Operations on the Graph

The Graph Operations menu button is used to perform miscellaneous actions on the graph.

Breakout

Creates new graphs for each of the metrics in the graph, adds them to the dashboard, and removes the original.

Clone

Creates a copy of the graph, and adds it to the dashboard.

Email

Allows you to send a copy of the graph to someone via email.

Direct URL

Provides the URL for rendering this graph, suitable for copying and pasting. Note that changing this URL does not affect the chart it came from, i.e. this is not a mechanism for editing the chart.

Other Global Menu Options

Editing, Importing and Exporting via JSON

The Dashboard | Edit Dashboard menu item shows a JSON (JavaScript Object Notation) representation of the current dashboard and all its graphs in an editor dialog.

If you’re a power user, you can edit the dashboard configuration directly. When you click the Update button, the changes are applied to the dashboard on screen only. This function also provides a convenient mechanism for importing and exporting dashboards, for instance to promote dashboards from development to production systems.

Sharing a Dashboard

The Share menu button shows a URL for the dashboard, allowing others to access it directly. This first warns you that your dashboard must be saved, then presents the URL.

Changing Graph Sizes

The Graphs | Resize menu item and the Gear menu button allow all graphs on the dashboard to be set to a specified size. You can either choose one of the preset sizes, or select Custom and enter your own width and height (in pixels).

New Dashboard

Selecting the Dashboard | New menu item removes the association between the current dashboard on the screen and its saved version (if any), which means that you’ll need to use Dashboard | Save As to save it again. Note that it doesn’t clear the contents of the dashboard, i.e. the graphs - use Remove All to achieve this.

Removing All Graphs

To remove all graphs on the current dashboard, use the Graphs | Remove All menu item or the red cross menu button. This asks for confirmation, and also gives you the option to skip confirmation in future.

Deleting a Dashboard

To delete a dashboard, open the Finder (using the Dashboard | Finder menu item), select the dashboard to delete in the list, and click Delete. Note that you may need to be logged in as a user with appropriate permissions to do this, depending on the configuration of Graphite.

Login/logout

By default, it’s not necessary to be logged in to use or change dashboards. However, your system may be configured to require users to be logged in to change or delete dashboards, and may also require appropriate permissions to do so.

Log into Graphite using the Dashboard | Log in menu item, which shows a standard login dialog. Once you’re logged in, the menu item changes to Log out from “username” - click this to log out again. Note that logins are recorded by a persistent browser cookie, so you don’t have to log in again each time you connect to Graphite.

Changing Default Graph Parameters

By default, graphs are generated with a standard render template. If you find yourself applying Render Options to each and every graph you create, then you can select Edit Default Parameters in the Graphs menu to automatically handle that. These parameters are saved with the dashboard and persisted in a cookie.

The format is as a set of key-value pairs separated by ampersands, like a query string. The keys and values come from The Render URL API and they’re all available. For example:

drawNullAsZero=true&graphOnly=true

Any new graphs created after saving that as the default graph parameters would have unreported metrics graphed as zeroes and omit the grid lines.