Commit 961cb6b2 by Diana Payton Committed by GitHub

Docs: Organize basic concepts and getting started (#21859)

* Update shortcuts.md

Removed content that was out-of-date and redundant with the UI.

* Added panels.md

* Added dashboards.md

* Added data-sources.md

* Update data-sources.md

* Sorted basic concepts into other topics

* Update docs/sources/menu.yaml

Co-Authored-By: Marcus Olsson <accounts+github@marcus.se.net>

* Update panels.md

* Update data-sources.md

Co-authored-by: Marcus Olsson <accounts+github@marcus.se.net>
parent 2c9b321c
+++
title = "Dashboard overview"
type = "docs"
[menu.docs]
identifier = "dashboards"
parent = "features"
weight = 1
+++
# Dashboard overview
A *dashboard* is a set of one or more panels organized and arranged into one or more rows. Grafana ships with a variety of Panels. Grafana makes it easy to construct the right queries, and customize the display properties so that you can create the perfect dashboard for your need. Each panel can interact with data from any configured Grafana Data Source (currently Graphite, Prometheus, Elasticsearch, InfluxDB, OpenTSDB, MySQL, PostgreSQL, Microsoft SQL Server and AWS Cloudwatch).
## Dashboard UI
<img src="/img/docs/v50/dashboard_annotated.png" class="no-shadow" width="700px">
1. Zoom out time range
2. Time picker dropdown. Here you can access relative time range options, auto refresh options and set custom absolute time ranges.
3. Manual refresh button. Will cause all panels to refresh (fetch new data).
4. Dashboard panel. You edit panels by clicking the panel title.
5. Graph legend. You can change series colors, y-axis and series visibility directly from the legend.
## Dashboard header
Click the new Dashboard link on the right side of the Dashboard picker. You now have a blank Dashboard.
<img class="no-shadow" src="/img/docs/v50/top_nav_annotated.png" width="580px">
The image above shows you the top header for a Dashboard.
1. Side menubar toggle: This toggles the side menu, allowing you to focus on the data presented in the dashboard. The side menu provides access to features unrelated to a Dashboard such as Users, Organizations, and Data Sources.
2. Dashboard dropdown: This dropdown shows you which Dashboard you are currently viewing, and allows you to easily switch to a new Dashboard. From here you can also create a new Dashboard or folder, Import existing Dashboards, and manage Dashboard playlists.
3. Add Panel: Adds a new panel to the current Dashboard
4. Star Dashboard: Star (or unstar) the current Dashboard. Starred Dashboards will show up on your own Home Dashboard by default, and are a convenient way to mark Dashboards that you're interested in.
5. Share Dashboard: Share the current dashboard by creating a link or create a static Snapshot of it. Make sure the Dashboard is saved before sharing.
6. Save dashboard: The current Dashboard will be saved with the current Dashboard name.
7. Settings: Manage Dashboard settings and features such as Templating and Annotations.
## Manage dashboards
The time period for the dashboard can be controlled by the [Time range controls]({{< relref "../reference/timerange.md" >}}) in the upper right of the dashboard.
Dashboards can use [templating]({{< relref "../reference/templating.md" >}}) to make them more dynamic and interactive.
Dashboards can use [annotations]({{< relref "../reference/annotations.md" >}}) to display event data across panels. This can help correlate the time series data in the panel with other events.
Dashboards can be [shared]({{< relref "../reference/share_dashboard.md" >}}) easily in a variety of ways.
Dashboards can be tagged, and the dashboard picker provides quick, searchable access to all dashboards in a particular organization.
## Rows
A *row* is a logical divider within a dashboard. It is used to group panels together.
Rows are always 12 “units” wide. These units are automatically scaled dependent on the horizontal resolution of your browser. You can control the relative width of panels within a row by setting their specific width.
We use a unit abstraction so that Grafana looks great on all screens sizes.
> Note: With MaxDataPoint functionality, Grafana can show you the perfect number of data points, regardless of resolution or time range.
Collapse a row by clicking on the row title. If you save a dashboard with a row collapsed, then it saves in that state and does not load those graphs until you expand the row.
Use the [repeating rows]({{< relref "../reference/templating.md#repeating-rows" >}}) functionality to dynamically create or remove entire rows, which can be filled with panels, based on the template variables selected.
+++
title = "Data sources overview"
description = "Overview of data sources in Grafana"
keywords = ["grafana", "data sources"]
type = "docs"
[menu.docs]
name = "Data sources overview"
parent = "datasources"
weight = 1
+++
# Data sources
Grafana can visualize, explore, and alert on data from many different databases and cloud services. Each database or service type is accessed from a *data source*.
Each data source has a specific query editor that is customized for the features and capabilities that the particular data source exposes. The query language and capabilities of each data source are obviously very different. You can combine data from multiple data sources into a single dashboard, but each panel is connected to a specific data source that belongs to a particular organization.
Use the query editor to build one or more queries in your time series database. The panel instantly updates, allowing you to effectively explore your data in real time and build a perfect query for that particular panel.
You can use [template variables]({{< relref "../../reference/templating.md" >}}) in the query editor within the queries themselves. This provides a powerful way to explore data dynamically based on the templating variables selected on the dashboard.
Grafana allows you to reference queries in the query editor by the row that they’re on. If you add a second query to graph, you can reference the first query by typing in #A. This provides an easy and convenient way to build compound queries.
\ No newline at end of file
+++
title = "Panel overview"
keywords = ["grafana", "panel", "documentation", "guide"]
type = "docs"
[menu.docs]
name = "Panels"
parent = "panels"
weight = 1
+++
# Panel overview
The *panel* is the basic visualization building block in Grafana. Each panel has a Query Editor specific to the data source selected in the panel. The query editor allows you to extract the perfect visualization to display on the panel.
There are a wide variety of styling and formatting options for each panel. Panels can be dragged and dropped and rearranged on the Dashboard. They can also be resized.
Panels like the [Graph]({{< relref "graph.md" >}}) panel allow you to graph as many metrics and series as you want. Other panels like [Singlestat]({{< relref "singlestat.md" >}}) require a reduction of a single query into a single number.
Panels can be made more dynamic with [Dashboard Templating]({{< relref "../../reference/templating.md" >}}) variable strings within the panel configuration. The template can include queries to your data source configured in the Query Editor.
Panels can be [shared]({{< relref "../../reference/share_panel.md" >}}) easily in a variety of ways.
## Adding and editing graphs and panels
![](/img/docs/v45/metrics_tab.png)
1. You add panels by clicking the Add panel icon on the top menu.
1. To edit the graph you click on the graph title to open the panel menu, then `Edit`.
1. This should take you to the `Metrics` tab. In this tab you should see the editor for your default data source.
When you click the `Metrics` tab, you are presented with a Query Editor that is specific to the Panel Data Source. Use the Query Editor to build your queries and Grafana will visualize them in real time.
## Move panels
You can drag and drop panels by clicking and holding the panel title, then dragging it to its new location. You can also easily resize panels by clicking the (-) and (+) icons.
![](/img/docs/animated_gifs/drag_drop.gif)
## Tips and shortcuts
* Click the graph title and in the dropdown menu quickly change span or duplicate the panel.
* Click the Save icon in the menu to save the dashboard with a new name.
* Click the Save icon in the menu and then advanced to export the dashboard to json file, or set it as your default dashboard.
* Click the colored icon in the legend to select series color.
* Click series name in the legend to hide series.
* Ctrl/Shift/Meta + click legend name to hide other series.
+++ +++
title = "Keyboard Shortcuts" title = "Keyboard shortcuts"
type = "docs" type = "docs"
[menu.docs] [menu.docs]
parent = "features" parent = "features"
...@@ -8,46 +8,11 @@ weight = 7 ...@@ -8,46 +8,11 @@ weight = 7
# Keyboard shortcuts # Keyboard shortcuts
{{< docs-imagebox img="/img/docs/v50/shortcuts.png" max-width="20rem" class="docs-image--right" >}} Grafana has a number of keyboard shortcuts available. Press Shift + `?` on your keyboard to display all keyboard shortcuts available in your version of Grafana.
Grafana v4 introduces a number of really powerful keyboard shortcuts. You can now focus a panel **Popular shortcuts:**
by hovering over it with your mouse. With a panel focused you can simple hit `e` to toggle panel
edit mode, or `v` to toggle fullscreen mode. `p` `r` removes the panel. `p` `s` opens share
modal.
Hit `?` on your keyboard to open the shortcuts help modal. * Ctrl+S saves the current dashboard.
* Ctrl+F opens the dashboard finder / search.
### Global * Ctrl+H hides all controls (good for tv displays).
* Press Escape to exit graph when in fullscreen or edit mode.
- `g` `h` Go to Home Dashboard
- `g` `p` Go to Profile
- `s` `o` Open search
- `s` `s` Open search with starred filter
- `s` `t` Open search in tags view
- `esc` Exit edit/setting views
### Dashboard
- `mod+s` Save dashboard
- `mod+h` Hide row controls
- `d` `r` Refresh all panels
- `d` `s` Dashboard settings
- `d` `v` Toggle in-active / view mode
- `d` `k` Toggle kiosk mode (hides top nav)
- `d` `E` Expand all rows
- `d` `C` Collapse all rows
- `mod+o` Toggle shared graph crosshair
### Focused Panel
- `e` Toggle panel edit view
- `v` Toggle panel fullscreen view
- `p` `s` Open Panel Share Modal
- `p` `d` Duplicate Panel
- `p` `r` Remove Panel
### Time Range
- `t` `z` Zoom out time range
- `t` Move time range back
- `t` Move time range forward
mod = Ctrl on Windows or Linux and Cmd key on macOS
+++
title = "Basic Concepts"
description = "Grafana intro and concept guide"
keywords = ["grafana", "intro", "guide", "concepts"]
type = "docs"
[menu.docs]
name = "Basic concepts"
identifier = "basic_concepts"
parent = "guides"
weight = 2
+++
# Basic concepts
This document is an introduction to basic concepts in Grafana. Use it as a starting point to get familiar with core Grafana features.
## Dashboard
The *dashboard* is where it all comes together. A dashboard is a set of one or more panels organized and arranged into one or more rows.
The time period for the dashboard can be controlled by the [Time range controls]({{< relref "../reference/timerange.md" >}}) in the upper right of the dashboard.
Dashboards can use [templating]({{< relref "../reference/templating.md" >}}) to make them more dynamic and interactive.
Dashboards can use [annotations]({{< relref "../reference/annotations.md" >}}) to display event data across panels. This can help correlate the time series data in the panel with other events.
Dashboards can be [shared]({{< relref "../reference/share_dashboard.md" >}}) easily in a variety of ways.
Dashboards can be tagged, and the dashboard picker provides quick, searchable access to all dashboards in a particular organization.
## Data source
Grafana can visualize, explore, and alert on data from many different databases and cloud services. Each database or service type is accessed from a *data source*.
Each data source has a specific query editor that is customized for the features and capabilities that the particular data source exposes. The query language and capabilities of each data source are obviously very different. You can combine data from multiple data sources into a single dashboard, but each panel is connected to a specific data source that belongs to a particular organization.
Refer to the [Data sources section]({{< relref "../features/datasources" >}}) for a list of data sources that Grafana officially supports.
## Organization
Grafana supports multiple *organizations* in order to support a wide variety of deployment models, including using a single Grafana instance to provide service to multiple potentially untrusted organizations.
In most cases, Grafana is deployed with a single organization.
Each organization can have one or more data sources.
All dashboards are owned by a particular organization.
> Note: Most metric databases do not provide per-user series authentication. This means that organization data sources and dashboards are available to all users in a particular organization.
Refer to [Organization roles]({{< relref "../permissions/organization_roles.md" >}}) for more information.
## Panel
The *panel* is the basic visualization building block in Grafana. Each panel has a Query Editor specific to the data source selected in the panel. The query editor allows you to extract the perfect visualization to display on the panel.
There are a wide variety of styling and formatting options for each panel. Panels can be dragged and dropped and rearranged on the Dashboard. They can also be resized.
Panels like the [Graph]({{< relref "../features/panels/graph.md" >}}) panel allow you to graph as many metrics and series as you want. Other panels like [Singlestat]({{< relref "../features/panels/singlestat.md" >}}) require a reduction of a single query into a single number.
Panels can be made more dynamic with [Dashboard Templating]({{< relref "../reference/templating.md" >}}) variable strings within the panel configuration. The template can include queries to your data source configured in the Query Editor.
Panels can be [shared]({{< relref "../reference/share_panel.md" >}}) easily in a variety of ways.
## Query editor
The *query editor* exposes capabilities of your data source and allows you to query the metrics that it contains.
Use the query editor to build one or more queries in your time series database. The panel instantly updates, allowing you to effectively explore your data in real time and build a perfect query for that particular panel.
You can use [template variables]({{< relref "../reference/templating.md" >}}) in the query editor within the queries themselves. This provides a powerful way to explore data dynamically based on the templating variables selected on the dashboard.
Grafana allows you to reference queries in the query editor by the row that they’re on. If you add a second query to graph, you can reference the first query by typing in #A. This provides an easy and convenient way to build compound queries.
## Row
A *row* is a logical divider within a dashboard. It is used to group panels together.
Rows are always 12 “units” wide. These units are automatically scaled dependent on the horizontal resolution of your browser. You can control the relative width of panels within a row by setting their specific width.
We use a unit abstraction so that Grafana looks great on all screens sizes.
> Note: With MaxDataPoint functionality, Grafana can show you the perfect number of data points, regardless of resolution or time range.
Collapse a row by clicking on the row title. If you save a dashboard with a row collapsed, then it saves in that state and does not load those graphs until you expand the row.
Use the [repeating rows]({{< relref "../reference/templating.md#repeating-rows" >}}) functionality to dynamically create or remove entire rows, which can be filled with panels, based on the template variables selected.
## User
A *user* is a named account in Grafana. A user can belong to one or more organizations and can be assigned different levels of privileges through roles.
Grafana supports a wide variety of internal and external ways for users to authenticate themselves. These include from its own integrated database, from an external SQL server, or from an external LDAP server.
Refer to the [Permissions overview](docs\sources\permissions\overview.md) for information about roles and permissions.
...@@ -15,19 +15,17 @@ weight = 1 ...@@ -15,19 +15,17 @@ weight = 1
This guide will help you get started and acquainted with Grafana. It assumes you have a working Grafana server up and running. If not please read the [installation guide]({{< relref "../installation/" >}}). This guide will help you get started and acquainted with Grafana. It assumes you have a working Grafana server up and running. If not please read the [installation guide]({{< relref "../installation/" >}}).
## Logging in for the first time ## Log in for the first time
To run Grafana open your browser and go to http://localhost:3000/. 3000 is the default HTTP port that Grafana listens to if you haven't [configured a different port]({{< relref "../installation/configuration/#http-port" >}}). To run Grafana, open your browser and go to http://localhost:3000/. 3000 is the default HTTP port that Grafana listens to if you haven't [configured a different port]({{< relref "../installation/configuration/#http-port" >}}).
There you will see the login page. Default username is admin and default password is admin. When you log in for the first time you will be asked to change your password. We strongly encourage you to There you will see the login page. Default username is admin and default password is admin. When you log in for the first time you will be asked to change your password. We strongly encourage you to follow Grafana’s best practices and change the default administrator password. You can later go to user preferences and change your user name.
follow Grafana’s best practices and change the default administrator password. You can later go to user preferences and change your user name.
## Add a data source
## How to add a data source
{{< docs-imagebox img="/img/docs/v52/sidemenu-datasource.png" max-width="250px" class="docs-image--right docs-image--no-shadow">}} {{< docs-imagebox img="/img/docs/v52/sidemenu-datasource.png" max-width="250px" class="docs-image--right docs-image--no-shadow">}}
Before you create your first dashboard you need to add your data source. Before you create your first dashboard, you need to add your data source.
First move your cursor to the cog on the side menu which will show you the configuration menu. If the side menu is not visible click the Grafana icon in the upper left corner. The first item on the configuration menu is data sources, click on that and you'll be taken to the data sources page where you can add and edit data sources. You can also simply click the cog. First move your cursor to the cog on the side menu which will show you the configuration menu. If the side menu is not visible click the Grafana icon in the upper left corner. The first item on the configuration menu is data sources, click on that and you'll be taken to the data sources page where you can add and edit data sources. You can also simply click the cog.
...@@ -42,73 +40,3 @@ First, give the data source a Name and then select which Type of data source you ...@@ -42,73 +40,3 @@ First, give the data source a Name and then select which Type of data source you
{{< docs-imagebox img="/img/docs/v52/datasource-settings.png" max-width="700px" class="docs-image--no-shadow">}} {{< docs-imagebox img="/img/docs/v52/datasource-settings.png" max-width="700px" class="docs-image--no-shadow">}}
After you have configured your data source you are ready to save and test. After you have configured your data source you are ready to save and test.
## Beginner guides
Watch the 10min [beginners guide to building dashboards](https://www.youtube.com/watch?v=sKNZMtoSHN4&index=7&list=PLDGkOdUX1Ujo3wHw9-z5Vo12YLqXRjzg2) to get a quick intro to setting up Dashboards and Panels.
## Basic concepts
Read the [Basic Concepts]({{< relref "basic_concepts" >}}) document to get a crash course in key Grafana concepts.
### Top header
Let's start with creating a new Dashboard. You can find the new Dashboard link on the right side of the Dashboard picker. You now have a blank Dashboard.
<img class="no-shadow" src="/img/docs/v50/top_nav_annotated.png" width="580px">
The image above shows you the top header for a Dashboard.
1. Side menubar toggle: This toggles the side menu, allowing you to focus on the data presented in the dashboard. The side menu provides access to features unrelated to a Dashboard such as Users, Organizations, and Data Sources.
2. Dashboard dropdown: This dropdown shows you which Dashboard you are currently viewing, and allows you to easily switch to a new Dashboard. From here you can also create a new Dashboard or folder, Import existing Dashboards, and manage Dashboard playlists.
3. Add Panel: Adds a new panel to the current Dashboard
4. Star Dashboard: Star (or unstar) the current Dashboard. Starred Dashboards will show up on your own Home Dashboard by default, and are a convenient way to mark Dashboards that you're interested in.
5. Share Dashboard: Share the current dashboard by creating a link or create a static Snapshot of it. Make sure the Dashboard is saved before sharing.
6. Save dashboard: The current Dashboard will be saved with the current Dashboard name.
7. Settings: Manage Dashboard settings and features such as Templating and Annotations.
## Dashboards, panels, the building blocks of Grafana...
Dashboards are at the core of what Grafana is all about. Dashboards are composed of individual Panels arranged on a grid. Grafana ships with a variety of Panels. Grafana makes it easy to construct the right queries, and customize the display properties so that you can create the perfect Dashboard for your need. Each Panel can interact with data from any configured Grafana Data Source (currently Graphite, Prometheus, Elasticsearch, InfluxDB, OpenTSDB, MySQL, PostgreSQL, Microsoft SQL Server and AWS Cloudwatch). The [Basic Concepts]({{< relref "basic_concepts" >}}) guide explores these key ideas in detail.
<img src="/img/docs/v50/dashboard_annotated.png" class="no-shadow" width="700px">
1. Zoom out time range
2. Time picker dropdown. Here you can access relative time range options, auto refresh options and set custom absolute time ranges.
3. Manual refresh button. Will cause all panels to refresh (fetch new data).
4. Dashboard panel. You edit panels by clicking the panel title.
5. Graph legend. You can change series colors, y-axis and series visibility directly from the legend.
## Adding and editing graphs and panels
![](/img/docs/v45/metrics_tab.png)
1. You add panels by clicking the Add panel icon on the top menu.
2. To edit the graph you click on the graph title to open the panel menu, then `Edit`.
3. This should take you to the `Metrics` tab. In this tab you should see the editor for your default data source.
When you click the `Metrics` tab, you are presented with a Query Editor that is specific to the Panel Data Source. Use the Query Editor to build your queries and Grafana will visualize them in real time.
## Drag-and-Drop panels
You can Drag-and-Drop Panels by simply clicking and holding the Panel title, and drag it to its new location. You can also easily resize panels by clicking the (-) and (+) icons.
![](/img/docs/animated_gifs/drag_drop.gif)
## Tips and shortcuts
* Click the graph title and in the dropdown menu quickly change span or duplicate the panel.
* Click the Save icon in the menu to save the dashboard with a new name
* Click the Save icon in the menu and then advanced to export the dashboard to json file, or set it as your default dashboard.
* Click the colored icon in the legend to select series color
* Click series name in the legend to hide series
* Ctrl/Shift/Meta + Click legend name to hide other series
## Grafana loves the keyboard
* Ctrl+S Saves the current dashboard
* Ctrl+F Opens the dashboard finder / search
* Ctrl+H Hides all controls (good for tv displays)
* Hit Escape to exit graph when in fullscreen or edit mode
...@@ -73,8 +73,6 @@ ...@@ -73,8 +73,6 @@
children: children:
- name: Getting Started - name: Getting Started
link: /guides/getting_started/ link: /guides/getting_started/
- name: Basic Concepts
link: /guides/basic_concepts/
- name: Glossary - name: Glossary
link: /guides/glossary/ link: /guides/glossary/
- name: Screencasts - name: Screencasts
...@@ -85,6 +83,8 @@ ...@@ -85,6 +83,8 @@
- name: Panels - name: Panels
link: /features/panels/ link: /features/panels/
children: children:
- link: /features/panels/panels/
name: Overview
- link: /features/panels/graph/ - link: /features/panels/graph/
name: Graph name: Graph
- link: /features/panels/logs/ - link: /features/panels/logs/
...@@ -104,6 +104,8 @@ ...@@ -104,6 +104,8 @@
- name: Dashboard Features - name: Dashboard Features
link: /features/dashboard/ link: /features/dashboard/
children: children:
- link: /features/dashboard/dashboards/
name: Overview
- link: /reference/templating/ - link: /reference/templating/
name: Variables name: Variables
- link: /reference/annotations/ - link: /reference/annotations/
......
...@@ -20,6 +20,12 @@ Grafana users have permissions that are determined by their: ...@@ -20,6 +20,12 @@ Grafana users have permissions that are determined by their:
- Via permissions assigned directly to user (on folders, dashboards, data sources) - Via permissions assigned directly to user (on folders, dashboards, data sources)
- The Grafana Admin (i.e. Super Admin) user flag. - The Grafana Admin (i.e. Super Admin) user flag.
## User
A *user* is a named account in Grafana. A user can belong to one or more organizations and can be assigned different levels of privileges through roles.
Grafana supports a wide variety of internal and external ways for users to authenticate themselves. These include from its own integrated database, from an external SQL server, or from an external LDAP server.
## Grafana Admin ## Grafana Admin
This admin flag makes a user a `Super Admin`. This means they can access the `Server Admin` views where all users and organizations can be administrated. This admin flag makes a user a `Super Admin`. This means they can access the `Server Admin` views where all users and organizations can be administrated.
...@@ -27,7 +33,17 @@ This admin flag makes a user a `Super Admin`. This means they can access the `Se ...@@ -27,7 +33,17 @@ This admin flag makes a user a `Super Admin`. This means they can access the `Se
## Organization Roles ## Organization Roles
Users can be belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do Users can be belong to one or more organizations. A user's organization membership is tied to a role that defines what the user is allowed to do
in that organization. Learn more about [Organization Roles]({{< relref "organization_roles.md" >}}). in that organization. Grafana supports multiple *organizations* in order to support a wide variety of deployment models, including using a single Grafana instance to provide service to multiple potentially untrusted organizations.
In most cases, Grafana is deployed with a single organization.
Each organization can have one or more data sources.
All dashboards are owned by a particular organization.
> Note: Most metric databases do not provide per-user series authentication. This means that organization data sources and dashboards are available to all users in a particular organization.
Refer to [Organization roles]({{< relref "../permissions/organization_roles.md" >}}) for more information.
## Dashboard and Folder Permissions ## Dashboard and Folder Permissions
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment