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 :ref:`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 :ref:`the functions page <list-of-functions>`. 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 :doc:`render_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 :ref:`param-title`.
Provides options for:
- fonts (see :ref:`param-fontName`, :ref:`param-fontBold`, :ref:`param-fontItalic`, :ref:`param-fontSize` and :ref:`param-fgcolor`)
- colors (see :ref:`param-colorList`, :ref:`param-bgcolor`, :ref:`param-majorGridLineColor`, :ref:`param-minorGridLineColor` and :ref:`param-areaAlpha`)
- legends (see :ref:`param-hideLegend` and :ref:`param-uniqueLegend`)
- line thickness (see :ref:`param-lineWidth`)
- hiding of graph elements (see :ref:`param-graphOnly`, :ref:`param-hideAxes`, :ref:`param-hideYAxis` and :ref:`param-hideGrid`)
- apply a template (see :ref:`param-template`).
- Line Mode
- Sets the way lines are rendered, e.g. sloped, staircase, connected, and how the value
Noneis rendered. See :ref:`param-lineMode` and :ref:`param-drawNullAsZero`.
- Area Mode
- Determines whether the area below lines is filled, and whether the lines are stacked. See :ref:`param-areaMode`.
- Allows setting the time format for dates/times on the axis (see :ref:`param-xFormat`), the timezone for interpretation of timestamps (see :ref:`param-tz`), and the threshold for point consolidation (the closest number of pixels between points before they are consolidated, see :ref:`param-minXStep`).
Determines how the Y-axis or axes are rendered. This includes:
- label (see :ref:`param-vtitle`)
- minimum/maximum values on the axis (see :ref:`param-yMin` and :ref:`param-yMax`)
- the number of minor lines to draw (see :ref:`param-minorY`)
- drawing on a logarithmic scale of the specified base (see :ref:`param-logBase`)
- step between the Y-axis labels and gridlines (see :ref:`param-yStep`)
- divisor for the axis (see :ref:`param-yDivisors`)
- unit system (SI, binary, or none - see :ref:`param-yUnitSystem`)
- side the axis appears (see :ref:`param-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.
Other Global Menu Options
Editing, Importing and Exporting via JSON
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.
The Update button does not save your changes - you'll need to use Save or Save As to do this.
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.
If you haven't yet saved your dashboard (ever), it will be given a name like "temporary-0", so you probably want to save it first. It's important to note that temporary dashboards are never shown in the Finder, and so the only way to delete them is via the Admin webapp or the database. You probably don't want that...
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).
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.
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 :doc:`render_api` and they're all available. For example:
Any new graphs created after saving that as the default graph parameters would have unreported metrics graphed as zeroes and omit the grid lines.