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.
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.
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.
The items in the list of metrics can be edited in place. Double-click the item, edit as required, then hit Enter to complete.
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
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.
All these actions use functions documented on the functions page. For further information, read the documentation for the appropriate function on that page. Function names are included in brackets in the list below.
The functions are grouped in the menu, as follows:
- 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.
- 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.
- 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)
- Functions that filter metric series from a group. Includes highest current value, current value above limit, most deviant, remove below percentile.
- 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.
Each of the items in this menu matches a graph parameter in the The Render URL API. For further information, read the documentation for the appropriate parameter on that page.
The functions are grouped as follows:
- Graph Title
- Unsurprisingly, this sets the title for the graph. See title.
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
Noneis rendered. See lineMode and drawNullAsZero.
- Area Mode
- Determines whether the area below lines is filled, and whether the lines are stacked. See areaMode.
- 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).
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 yDivisor)
- 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.
- Creates new graphs for each of the metrics in the graph, adds them to the dashboard, and removes the original.
- Creates a copy of the graph, and adds it to the dashboard.
- 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.