public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Reorganize reference topics (#25915)

Browse Source 
* moved annotations.md

* Update annotations.md

* moved dashboard_folders.md

* moved dashboard_history.md

* moved playlist.md

* moved search.md
This commit is contained in:
Diana Payton
2020-06-30 14:18:38 -07:00
committed by GitHub
parent d4239e6fd2
commit e07d0ae452
19 changed files with 27 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/reference/annotations.md
-78
View File
@@ -1,78 +0,0 @@
+++
title = "Annotations"
keywords = ["grafana", "annotations", "documentation", "guide"]
type = "docs"
[menu.docs]
name = "Annotations"
parent = "dashboard_features"
weight = 2
+++
# Annotations
{{< docs-imagebox img="/img/docs/v46/annotations.png" max-width="800px" >}}
Annotations provide a way to mark points on the graph with rich events. When you hover over an annotation
you can get event description and event tags. The text field can include links to other systems with more detail.
## Native annotations
Grafana v4.6+ comes with a native annotation store and the ability to add annotation events directly from the graph panel or via the [HTTP API]({{< relref "../http_api/annotations.md" >}}).
## Adding annotations
By holding down Ctrl/Cmd+Click. Adding tags to the annotation will make it searchable from other dashboards.
{{< docs-imagebox img="/img/docs/annotations/annotation-still.png"
max-width="600px" animated-gif="/img/docs/annotations/annotation.gif" >}}
### Adding regions events
You can also hold down Ctrl/Cmd and select region to create a region annotation.
{{< docs-imagebox img="/img/docs/annotations/region-annotation-still.png"
max-width="600px" animated-gif="/img/docs/annotations/region-annotation.gif" >}}
### Built in query
After you added an annotation they will still be visible. This is due to the built in annotation query that exists on all dashboards. This annotation query will
fetch all annotation events that originate from the current dashboard and show them on the panel where they were created. This includes alert state history annotations. You can
stop annotations from being fetched and drawn by opening the **Annotations** settings (via Dashboard cogs menu) and modifying the query named `Annotations & Alerts (Built-in)`.
When you copy a dashboard using the **Save As** feature it will get a new dashboard id so annotations created on source dashboard will no longer be visible on the copy. You
can still show them if you add a new **Annotation Query** and filter by tags. But this only works if the annotations on the source dashboard had tags to filter by.
### Query by tag
You can create new annotation queries that fetch annotations from the native annotation store via the `-- Grafana --` data source and by setting *Filter by* to `Tags`. Specify at least
one tag. For example create an annotation query name `outages` and specify a tag named `outage`. This query will show all annotations you create (from any dashboard or via API) that have the `outage` tag. By default, if you add multiple tags in the annotation query, Grafana will only show annotations that have all the tags you supplied. You can invert the behavior by enabling `Match any` which means that Grafana will show annotations that contains at least one of the tags you supplied.
In Grafana v5.3+ it's possible to use template variables in the tag query. So if you have a dashboard showing stats for different services and a template variable that dictates which services to show, you can now use the same template variable in your annotation query to only show annotations for those services.
{{< docs-imagebox img="/img/docs/v53/annotation_tag_filter_variable.png" max-width="600px" >}}
## Querying other data sources
Annotation events are fetched via annotation queries. To add a new annotation query to a dashboard
open the dashboard settings menu, then select `Annotations`. This will open the dashboard annotations
settings view. To create a new annotation query hit the `New` button.
<!--![](/img/docs/v50/annotation_new_query.png)-->
{{< docs-imagebox img="/img/docs/v50/annotation_new_query.png" max-width="600px" >}}
Specify a name for the annotation query. This name is given to the toggle (checkbox) that will allow
you to enable/disable showing annotation events from this query. For example you might have two
annotation queries named `Deploys` and `Outages`. The toggle will allow you to decide what annotations
to show.
### Annotation query details
The annotation query options are different for each data source.
- [Graphite annotation queries]({{< relref "../features/datasources/graphite.md#annotations" >}})
- [Elasticsearch annotation queries]({{< relref "../features/datasources/elasticsearch.md#annotations" >}})
- [InfluxDB annotation queries]({{< relref "../features/datasources/influxdb.md#annotations" >}})
- [Prometheus annotation queries]({{< relref "../features/datasources/prometheus.md#annotations" >}})
- [MySQL annotation queries]({{< relref "../features/datasources/mysql.md#annotations" >}})
- [Postgres annotation queries]({{< relref "../features/datasources/postgres.md#annotations" >}})
- [Loki annotation queries]({{< relref "../features/datasources/loki.md#annotations" >}})
docs/sources/reference/dashboard_folders.md
-52
View File
@@ -1,52 +0,0 @@
+++
title = "Dashboard Folders"
keywords = ["grafana", "dashboard", "dashboard folders", "folder", "folders", "documentation", "guide"]
type = "docs"
[menu.docs]
name = "Folders"
parent = "dashboard_features"
weight = 3
+++
# Dashboard Folders
Folders are a way to organize and group dashboards - very useful if you have a lot of dashboards or multiple teams using the same Grafana instance.
## How To Create A Folder
- Create a folder by using the Create Folder link in the side menu (under the create menu (+ icon))
- Use the create Folder button on the Manage Dashboards page.
- When saving a dashboard, you can either choose a folder for the dashboard to be saved in or create a new folder
On the Create Folder page, fill in a unique name for the folder and press Create.
## Manage Dashboards
{{< docs-imagebox img="/img/docs/v50/manage_dashboard_menu.png" max-width="300px" class="docs-image--right" >}}
There is a new Manage Dashboards page where you can carry out a variety of tasks:
- create a folder
- create a dashboard
- move dashboards into folders
- delete multiple dashboards
- navigate to a folder page (where you can set permissions for a folder and/or its dashboards)
## Dashboard Folder Page
You reach the dashboard folder page by clicking on the cog icon that appears when you hover
over a folder in the dashboard list in the search result or on the Manage dashboards page.
The Dashboard Folder Page is similar to the Manage Dashboards page and is where you can carry out the following tasks:
- Allows you to move or delete dashboards in a folder.
- Rename a folder (under the Settings tab).
- Set permissions for the folder (inherited by dashboards in the folder).
## Permissions
Permissions can be assigned to a folder and inherited by the containing dashboards. An Access Control List (ACL) is used where
**Organization Role**, **Team** and Individual **User** can be assigned permissions. Read the
[Dashboard and Folder Permissions]({{< relref "../permissions/dashboard_folder_permissions.md" >}}) docs for more detail
on the permission system.
docs/sources/reference/dashboard_history.md
-40
View File
@@ -1,40 +0,0 @@
+++
title = "Dashboard Version History"
keywords = ["grafana", "dashboard", "documentation", "version", "history"]
type = "docs"
[menu.docs]
name = "Dashboard Version History"
parent = "dashboard_features"
weight = 100
+++
# Dashboard Version History
Whenever you save a version of your dashboard, a copy of that version is saved so that previous versions of your dashboard are never lost. A list of these versions is available by entering the dashboard settings and then selecting "Versions" in the left side menu.
<img class="no-shadow" src="/img/docs/v50/dashboard_versions_list.png">
The dashboard version history feature lets you compare and restore to previously saved dashboard versions.
## Comparing two dashboard versions
To compare two dashboard versions, select the two versions from the list that you wish to compare. Once selected, the "Compare versions" button will become clickable. Click the button to view the diff between the two versions.
<img class="no-shadow" src="/img/docs/v50/dashboard_versions_select.png">
Upon clicking the button, you'll be brought to the diff view. By default, you'll see a textual summary of the changes, like in the image below.
<img class="no-shadow" src="/img/docs/v50/dashboard_versions_diff_basic.png">
If you want to view the diff of the raw JSON that represents your dashboard, you can do that as well by clicking the "View JSON Diff" button at the bottom.
If you want to restore to the version you are diffing against, you can do so by clicking the "Restore to version \<x\>" button in the top right.
## Restoring to a previously saved dashboard version
If you need to restore to a previously saved dashboard version, you can do so by either clicking the "Restore" button on the right of a row in the dashboard version list, or by clicking the "Restore to version \<x\>" button appearing in the diff view. Clicking the button will bring up the following popup prompting you to confirm the restoration.
<img class="no-shadow" src="/img/docs/v50/dashboard_versions_restore.png">
After restoring to a previous version, a new version will be created containing the same exact data as the previous version, only with a different version number. This is indicated in the "Notes column" for the row in the new dashboard version. This is done simply to ensure your previous dashboard versions are not affected by the change.
docs/sources/reference/playlist.md
-152
View File
@@ -1,152 +0,0 @@
+++
title = "Playlist"
keywords = ["grafana", "dashboard", "documentation", "playlist"]
type = "docs"
[menu.docs]
parent = "dashboard_features"
identifier = "feature_playlist"
weight = 4
+++
# Playlist
A playlist is a list of dashboards that are displayed in a sequence. You might use a playlist to build situational awareness or to present your metrics to your team or visitors.
Grafana automatically scales dashboards to any resolution, which makes them perfect for big screens.
You can access the Playlist feature from Grafana's side menu, in the Dashboards submenu.
{{< docs-imagebox img="/img/docs/v50/playlist.png" max-width="25rem">}}
## Create a playlist
You create a playlist to present dashboards in a sequence, with a set order and time interval between dashboards.
1. To access the Playlist feature, hover your cursor over Grafana's side menu.
1. Click **Playlists**.
1. Click **New playlist**.
1. In the **Name** text box, enter a name for your playlist.
1. In the **Interval** text box, enter a time interval.
The time interval is the amount of time for Grafana to stay on a particular dashboard before advancing to the next one on the playlist.
1. Next to the dashboard(s) you want to add to your playlist, click **Add to playlist**.
1. Click **Create**.
## Edit a playlist
You can edit playlists while creating them or after saving them.
1. To access the Playlist feature, hover your cursor over Grafana's side menu.
1. Click **Playlists**.
1. Click on the Playlist that you want to edit.
### Edit the Name of a playlist
1. Double-click within the **Name** text box.
1. Enter a name.
1. Click **Save** to save your changes.
### Edit the Interval of a playlist
1. Double-click within the **Interval** text box.
1. Enter a time interval.
1. Click **Save** to save your changes.
### Add a dashboard to a playlist
1. Next to the dashboard you want to add, click **Add to playlist**.
1. Click **Save** to save your changes.
### Search for a dashboard to add
1. Click the **Search dashboards by name** text box.
1. Search for the playlist by name or regular expression.
1. If needed, filter your results by starred status or tags.
By default, your starred dashboards will appear as options to add to the Playlist.
1. Click **Save** to save your changes.
### Rearrange dashboard order
1. Next to the dashboard you want to move, click the up or down arrow.
1. Click **Save** to save your changes.
### Remove a dashboard
1. Click **Remove[x]** to remove a dashboard from the playlist.
1. Click **Save** to save your changes.
### Delete a playlist
1. Click **Playlists**.
1. Next to the Playlist you want to delete, click **Remove[x]**.
## Save a playlist
You can save a playlist to add it to your **Playlists** page, where you can start it. Be sure that all the dashboards you want to appear in your playlist are added when creating or editing the playlist before saving it.
1. To access the Playlist feature, hover your cursor over Grafana's side menu.
1. Click **Playlists**.
1. Click on the playlist.
1. Edit the playlist.
* Ensure that your playlist has a **Name**, **Interval**, and at least one **Dashboard** added to it.
1. Click **Save**.
## Start a playlist
You can start a playlist in five different view modes, which determine how the menus and navigation bar are displayed on the dashboards.
By default, each dashboard is displayed for the amount of time entered in the Interval field, which can be set while creating or editing a playlist. Once a playlist is started, it can be controlled using the navbar at the top of your screen.
1. From the Dashboards submenu, click **Playlists**.
1. Next to the playlist you want to start, click **Start playlist**.
1. In the dropdown, select the mode you want the playlist to display in.
- **Normal mode:**
- The side menu remains visible.
- The navbar, row and panel controls appear at the top of the screen.
- **TV mode:**
- The side menu is hidden/removed.
- The navbar, row and panel controls appear at the top of the screen.
- Enabled automatically after one minute of user inactivity.
- You can enable it manually using the `d v` sequence shortcut, or by appending the parameter `?inactive` to the dashboard URL.
- You can disable it with any mouse movement or keyboard action.
- **TV mode (with auto fit panels):**
- The side menu is hidden/removed.
- The navbar, row and panel controls appear at the top of the screen.
- Dashboard panels automatically adjust to optimize space on screen.
- **Kiosk mode:**
- The side menu, navbar, row and panel controls are completely hidden/removed from view.
- You can enable it manually using the `d v` sequence shortcut after the playlist has started.
- You can disable it manually with the same shortcut.
- **Kiosk mode (with auto fit panels):**
- The side menu, navbar, row and panel controls are completely hidden/removed from view.
- Dashboard panels automatically adjust to optimize space on screen.
## Control a playlist
You can control a playlist in **Normal** or **TV** mode after it's started, using the navigation bar at the top of your screen.
| Button | Result |
| --- | --- |
| Next (double-right arrow) | Advances to the next dashboard. |
| Back (left arrow) | Returns to the previous dashboard. |
| Stop (square) | Ends the playlist, and exits to the current dashboard. |
| Cycle view mode (monitor icon) | Rotates the display of the dashboards in different view modes. |
| Time range | Displays data within a time range. It can be set to display the last 5 minutes up to 5 years ago, or a custom time range, using the down arrow. |
| Refresh (circle arrow) | Reloads the dashboard, to display the current data. It can be set to reload automatically every 5 seconds to 1 day, using the drop down arrow. |
> Shortcut: Press the Esc key to stop the playlist from your keyboard.
## Share a playlist in a view mode
You can share a playlist by copying the link address on the view mode you prefer, and pasting the URL to your destination.
1. From the Dashboards submenu, click **Playlists**.
1. Next to the playlist you want to share, click **Start playlist**.
1. In the dropdown, right click the view mode you prefer.
1. Click **Copy Link Address** to copy the URL to your clipboard.
Example: The URL for the first playlist on the Grafana Play site in Kiosk mode will look like this:
[https://play.grafana.org/playlists/play/1?kiosk](https://play.grafana.org/playlists/play/1?kiosk).
1. Paste the URL to your destination.
docs/sources/reference/search.md
-45
View File
@@ -1,45 +0,0 @@
+++
title = "Search"
keywords = ["grafana", "dashboard", "documentation", "search"]
type = "docs"
[menu.docs]
parent = "dashboard_features"
weight = 5
+++
# Dashboard Search
Dashboards can be searched by the dashboard name, filtered by one (or many) tags or filtered by starred status. The dashboard search is accessed through the dashboard picker, available in the dashboard top nav area. The dashboard search can also be opened by using the shortcut `F`.
<img class="no-shadow" src="/img/docs/v50/dashboard_search_annotated.png" width="700px">
1. `Search Bar`: The search bar allows you to enter any string and search both database and file based dashboards in real-time.
2. `Starred`: Here you find all your starred dashboards.
3. `Recent`: Here you find the latest created dashboards.
4. `Folders`: The tags filter allows you to filter the list by dashboard tags.
5. `Root`: The root contains all dashboards that are not placed in a folder.
6. `Tags`: The tags filter allows you to filter the list by dashboard tags.
When using only a keyboard, you can use your keyboard arrow keys to navigate the results, hit enter to open the selected dashboard.
## Find by dashboard name
Begin typing any part of the desired dashboard names in the search bar. Search will return results for any partial string match in real-time, as you type.
Dashboard search is:
- Real-time
- *Not* case sensitive
- Functional across stored *and* file based dashboards.
## Filter by Tag(s)
Tags are a great way to organize your dashboards, especially as the number of dashboards grow. Tags can be added and managed in the dashboard `Settings`.
To filter the dashboard list by tag, click on any tag appearing in the right column. The list may be further filtered by clicking on additional tags:
Alternately, to see a list of all available tags, click the tags dropdown menu. All tags will be shown, and when a tag is selected, the dashboard search will be instantly filtered:
When using only a keyboard: `tab` to focus on the *tags* link, `▼` down arrow key to find a tag and select with the `Enter` key.
**Note**: When multiple tags are selected, Grafana will show dashboards that include **all**.