# Graphite Dashboard Guide

Contents

* [Graphite Dashboard Guide](graphite-dashboard-guide)
  * [Creating a Graph](#creating-a-graph)
  * [Choosing a Time Range](#choosing-a-time-range)
  * [Graph Labeling and Styling](#graph-labeling-and-styling)
  * [Creating a Graphite Dashboard](#creating-a-graphite-dashboard)
  * [Saving and Loading Dashboards](#saving-and-loading-dashboards)
  * [Advanced Dashboard Configuration](#advanced-dashboard-configuration)

**NOTE**: We have removed Graphite Composer from the HG application in favor of Grafana. If you require Graphite Composer for any reason, please reach out to us and we will activate it in your account.





In the following guide, we’ll walk you through creating a simple Graphite graph for a chosen metric and adding that to a dashboard that you can bookmark for quick access. If you haven’t sent any metrics to Hosted Graphite yet, check out our [_Sending Metrics Guide_](../sending-metrics).

[_In this example_](../../welcome-to-hosted-graphite#a-simple-example), we’re using a metric called `conc_users` - the number of users logged into our imaginary application. We have been sending the metric value (such as the one below) once a minute to Hosted Graphite for the last day.

```sh
conc_users 1215
```

### [Creating a Graph](#creating-a-graph)

Let’s set up a graph for our `conc_users` metric. Log into Hosted Graphite, navigate to Dashboards, and select **Graphite Composer**.

When that opens, you’ll be presented with a blank composer dialog. On the tree on the left-hand side, expand the ‘Graphite’ folder. This will contain all the metrics sent using the [_API Key_](../../welcome-to-hosted-graphite#api-key) associated with your account. At the moment, there’s only one entry - our demo `conc_user` metric, so we click on that.

<figure><img src="https://www.hostedgraphite.com/docs/_images/composer-choosemetric.png" alt=""><figcaption><p>Choosing our <code>conc_user</code> metric</p></figcaption></figure>

**Tip**: If you’re going to be sending a wide range of metrics to a Hosted Graphite account, this ‘Graphite’ folder could soon have an unmanageable number of entries. Using periods in your [_metric names_](../../welcome-to-hosted-graphite#metric-data-format) will introduce a folder structure, allowing for logical grouping of your metrics. E.g. `servers.mario.memory.free` will result in `Graphite\servers\mario\memory\free` in the tree above. See the [Graphite Project website](https://graphite.readthedocs.io/en/latest/feeding-carbon.html#step-1-plan-a-naming-hierarchy) for more info.

When we click on our conc\_users metric, Graphite will render a graph of a recent selection that metric data:

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FJErYibYafUTbv5LFNq16%2Fimage.png?alt=media&#x26;token=3638e045-4d3f-4454-b0ff-77a7f8f12fe8" alt=""><figcaption><p>A graph of the <code>conc_user metric</code> after clicking on the <code>conc_user</code> entry</p></figcaption></figure>

### [Choosing a Time Range](#choosing-a-time-range)

The next thing we do is to choose how much of our data we’re going to sample. We have two options, via the following icons:

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2F8l70nwFdPunHSMOVa7Dc%2Fimage.png?alt=media&#x26;token=9dccd224-3dc9-463f-80b6-92265414bdb5" alt=""><figcaption><p>‘<em>Select A Date Range</em>‘ and ‘<em>Select Recent Data</em>‘ buttons</p></figcaption></figure>

*   **Select A Date Range**

    Choose a start date/time and an end date/time. This is useful for debugging a new metric, or for investigating an incident that occurred during a specific time window.
*   **Select Recent Data**

    View a rolling window of the most recent metric data, up to a specified number of minutes/hours/days/weeks/months/years.

**Tip** - If you make changes but the graph doesn’t update automatically, use the **Update Graph** button to trigger a refresh of the graph.

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2F4QfQ0LRUQxLgYMz2yF5e%2Fimage.png?alt=media&#x26;token=0f239c89-9e90-41ae-819e-437a43e46095" alt=""><figcaption><p>‘<em>Update Graph</em>‘ Button</p></figcaption></figure>

In this example, we want a view of the last 12 hours of the conc\_users metric, so click **Select Recent Data** and enter the appropriate values.

### [Graph Labeling and Styling](#graph-labeling-and-styling)

There are many options to make your data more presentable. At the bottom of the composer window, you’ll find a group of menus. These contain various functions to let you apply data transformations, labeling, and styling to your graph:

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FzzeVLrzQeH5hhJtOhv3o%2Fimage.png?alt=media&#x26;token=bcba98ee-2631-4789-a5f5-48a75d19689d" alt=""><figcaption><p>Composer Menus</p></figcaption></figure>

In this example, we’ll use only a few of the many available options. You can find more information about the menus in the [_graph menu guide_](graphite-graph-menu-reference). Let’s make the following adjustments to our graph:

* **Graph Options** -> **Line Mode** -> **Connected Line**Makes our graph a continuous line through our available metric points.
* **Graph Options** -> **Graph Title**Sets the title to `Site Visitors`.
* **Graph Options** -> **Display** -> **Line Thickness**Set this value to `3` (pixels) for a slightly thicker line than the default.
* **Graph Options** -> **X-Axis** -> **TimeZone**Metric timestamps are sent in UTC. The server (in this example) sending the metrics is in Dublin - Set this to `Europe/Dublin` to apply the appropriate offset to the X-axis timestamps.
* **Graph Options** -> **Y-Axis** -> **Label**Set the vertical axis label to `Users`.

This results in the following:

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FU2ubK0xWZisdwj5BTleb%2Fimage.png?alt=media&#x26;token=5eb57130-2e98-4eb9-8eca-d913b1ff9b88" alt=""><figcaption><p>A improved graph of the <code>conc_user</code> metric</p></figcaption></figure>

Click on the floppy disk icon in the composer toolbar to save. You’ll be prompted for a name, enter `Site Visitors`, and click OK. Your graph is now saved and can be recalled at any time by browsing **My Graphs** in the left-hand window of the Composer.

### [Creating a Graphite Dashboard](#creating-a-graphite-dashboard)

The final step in this tutorial is to create a bookmarkable Graphite dashboard and add your graph for display. Having followed the tutorial above, we will have a new `Site Visitors` graph in our account. Navigate to Dashboards -> Graphite Composer -> Dashboard in your Hosted Graphite account.

When you first open the dashboard page, you’ll be presented with a blank dashboard. Go to **Graphs** -> **New Graph** -> **From Saved Graph**

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2Fv1n6oXwStHq5j4XmoC2Z%2Fimage.png?alt=media&#x26;token=cbe4701b-88a1-4382-99d5-be05ed992583" alt=""><figcaption><p>Loading our saved Graph</p></figcaption></figure>

In the dialog that opens, an entry called `Site Visitors` will appear. Choose it and then click **Select**. Your graph will appear in the dashboard. Let’s make our graph a little bigger. Click on **Graphs** -> **Resize**, and choose the `Custom` option. Enter in a width of `800` and a height of `500` (or whatever suits your display).

**Tip** You can further customize the graphs for this dashboard instance by clicking a graph once to focus it, and clicking once more to bring up a configuration menu (This is the same menu we used when creating the graph - See [_Graphite Graph Menu Reference_](graphite-graph-menu-reference) for more info).

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2FCIVYu0Pem6Uz1yFUtrjj%2Fimage.png?alt=media&#x26;token=41d7f414-044d-4b7a-8506-6d13dc136d4d" alt=""><figcaption><p>Our Final Dashboard!</p></figcaption></figure>

### [Saving and Loading Dashboards](#saving-and-loading-dashboards)

To save your finished dashboard, click **Dashboard** -> **Save As** and enter a name, e.g. `MainSiteDash`.

To get a bookmarkable URL (which will directly open this dashboard instance), click on **Share** in the menu. A dialog will appear (you may be asked to save again) containing a URL that you can copy.

Finally, you can see all dashboards that you own by clicking **Dashboard** -> **Finder**. A dialog will appear with a list of all the dashboards that you have saved.

### [Advanced Dashboard Configuration](#advanced-dashboard-configuration)

**Graph Data**

In [_Creating A Dashboard_](#creating-a-graphite-dashboard), we created a simple graph with some basic styling. Graphite offers many more configuration options. You have the ability to show multiple metrics in the same graph, apply transformations to the metric data, or combine metrics before rendering. All of these advanced features are found via the **Graph Data** button:

_Graph Data_ button

Each time a metric is selected (in the [_tree of metrics_](#creating-a-graph)), an entry called a ‘target’ is added to the Graph Data dialog. For example, had we clicked on metric **\servers\smithers\users\_authed** and then metric **\servers\smithers\users\_guest** in the composer, the **Graph Data** dialog would contain two targets as follows (which would each result in a line on the graph):

<figure><img src="https://495119770-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtHmoGZNsmARIViZEdbz%2Fuploads%2Fmys4RxbonNkTwzLAMAMs%2Fimage.png?alt=media&#x26;token=b1b22890-e3ba-4ce2-aab8-f34abb5583f6" alt=""><figcaption><p><em>Graph Data</em> button</p></figcaption></figure>

#### **Wildcards**

Sometimes we want to display groups of common metrics. Rather than manually adding each metric as a target, we can use wildcards to specify multiple metrics as one target. Using the **Edit** button in the Graph Data dialog, we can manually specify the target as in the following examples:

*   To graph all the metrics under the **smithers** server:

    Set the target as **servers.smithers.\***
*   To graph the **users\_authed** metric on all servers:

    Set the target as **servers.\*.users\_authed**

**Graph Performance**

If you have many metrics stored with us, and your graphs are taking a long time to load, chances are that your [_wildcard use_](#wildcards) is the first place you should look. Try to avoid wildcards such as the following:

```
servers.*.*.cpu
```

In this case, every single metric matched by this wildcard will be queried, even if many of those metrics don’t have data for the selected time range. Multiple, but narrower targets in a graph may result in faster load times than one widely defined target.

In our example above, perhaps all we care about are our metrics regarding public-facing machines, but our wildcard is also including metrics from our production or staging machines. In this scenario, we replace the single target with two narrower targets, e.g.:

```
servers.production.*.cpu
servers.staging.*.cpu
```

**Data Transformations**

Now that we’ve defined _which_ metrics we’re interested in, we can perform transformations on them. Back in the **Graph Data** dialog, when we select a target (or multiple targets), we can use the **Apply Function** menu to alter or combine our targets in some way. When a function is applied to a target, you’ll notice that the target’s text changes, eg

```sh
before: original_target_text

after:  functionName(original_target_text)   or
        functionName(original_target_text, optional_params..)
```

Eg, if we selected _conc\_users_, and clicked **Apply Function** –> **Transform** –> **Derivative**, the target text would now say

The graph should automatically update to show the derivative of our _conc\_users_ metric. If not, click the refresh button. If several transformations are applied to a target, the function calls are nested, with the most recent one on the outside. E.g.

```python
lastFunction(secondFunction(firstFunction(original_target)))
```

To undo a function you just applied, click the target and use the **Undo Function**. The outermost function will be removed from the target text. You don’t have to use the **Apply Function** menu - you may also select your target, click **Edit**, then manually edit the target text by hand.

A quick summary of the **Apply Function** menu is as follows. Some functions are used on multiple targets (either by selecting multiple entries in the dialog, using wildcards, or both). More information about functions can be found on the _Functions_ page on the [Graphite Docs Page](https://graphite.readthedocs.io/).

*   **Combine**

    Combining the data points from multiple metrics using functions such as **sum()**
*   **Transform**

    Create a new set of data points after applying a transformation such as derivation or timeshifting to the input.
*   **Calculate**

    Perform running calculations on the data points such as a moving average, or forecasts.
*   **Filter**

    Discard, limit or maintain counts/maximums/minimums of the data points.
*   **Special**

    Miscellaneous functions, mostly contain routines that control the appearance of that target on the graph - For example setting a legend name or line color.
