forked from github/docs
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
KBase migration - Grafana tutorial (github#186)
* Copy-edit intro * Add raw content from KBase * Create new service * Light editing for untested bits. * Edited Installation section * Reflow * Reflow & fix image links * Remove extra whitespace * Apply suggestions from code review Co-authored-by: Ryan Booz <ryan@timescale.com> Co-authored-by: Ryan Booz <ryan@timescale.com> Co-authored-by: Jacob Prall <prall.jacob@gmail.com>
- Loading branch information
3 people
authored
Aug 23, 2021
1 parent
e172a01
commit 4a606e4
Showing
2 changed files
with
83 additions
and
81 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,34 +1,28 @@ | ||
| # Getting Started with Grafana and TimescaleDB | ||
|
|
||
| [Grafana][grafana-website] is an open source analytics and monitoring solution | ||
| often used to visualize time-series data. In these tutorials, you’ll learn how to: | ||
|
|
||
| - Setup Grafana and [TimescaleDB][install-timescale] | ||
| - Use Grafana to visualize metrics stored in TimescaleDB | ||
| - Visualize geospatial data using Grafana | ||
|
|
||
| Follow these tutorials: | ||
|
|
||
| - [Creating a Grafana dashboard and panel][tutorial-grafana-dashboards] to visualize data in TimescaleDB. | ||
| - [Visualize Geospatial data in Grafana][tutorial-grafana-geospatial]. | ||
| - [Use Grafana variables][tutorial-grafana-variables] to filter and customize your visualizations. | ||
| - [Visualize missing data in Grafana][tutorial-grafana-missing-data] using TimescaleDB features. | ||
| - [Setup Grafana alerts][tutorial-grafana-alerts] on time-series data using Slack, PagerDuty, and more. | ||
|
|
||
| ### Prerequisites for Grafana tutorials | ||
|
|
||
| To complete these tutorials, you will need a cursory knowledge of the Structured Query | ||
| Language (SQL). Each tutorial will walk you through each SQL command, but it will be | ||
| [Grafana][grafana-website] is an open source analytics and monitoring tool that | ||
| you can use visualize time-series data. Use these tutorials to: | ||
|
|
||
| * Set up [TimescaleDB and Grafana][install-grafana]. | ||
| * Create a [Grafana dashboard and panel][tutorial-grafana-dashboards] to | ||
| visualize data in TimescaleDB. | ||
| * Visualize [Geospatial data in Grafana][tutorial-grafana-geospatial]. | ||
| * Use [Grafana variables][tutorial-grafana-variables] to filter and customize | ||
| your visualizations. | ||
| * Visualize [missing data in Grafana][tutorial-grafana-missing-data] using | ||
| TimescaleDB features. | ||
| * Set up [Grafana alerts][tutorial-grafana-alerts] for Slack, PagerDuty, and | ||
| other tools. | ||
|
|
||
| ## Before you begin | ||
| To complete this tutorial, you need at least some knowledge of SQL (structured | ||
| query language). The tutorial walks you through each SQL command, but it is | ||
| helpful if you've seen SQL before. | ||
|
|
||
| * To start, [install TimescaleDB][install-timescale]. | ||
| * Next [setup Grafana][install-grafana]. | ||
|
|
||
| [install-timescale]: /how-to-guides/install-timescaledb/ | ||
| [grafana-website]: https://www.grafana.com | ||
| [install-grafana]: /tutorials/grafana/installation | ||
| [tutorial-grafana-dashboards]: /tutorials/grafana/create-dashboard-and-panel/ | ||
| [tutorial-grafana-geospatial]: /tutorials/grafana/geospatial-dashboards/ | ||
| [tutorial-grafana-variables]: /tutorials/grafana/grafana-variables/ | ||
| [tutorial-grafana-missing-data]: /tutorials/grafana/visualize-missing-data/ | ||
| [tutorial-grafana-alerts]: /tutorials/grafana/setup-alerts/ | ||
| [grafana-website]: https://www.grafana.com |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,59 +1,67 @@ | ||
| # Installing Grafana for use with TimescaleDB | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| You will need to [setup an instance of TimescaleDB][install-timescale]. | ||
|
|
||
| ### Options for installing Grafana | ||
|
|
||
| The easiest option for installing Grafana is to use Timescale Cloud. Alternatively, | ||
| you can setup your own instance of Grafana. | ||
|
|
||
| #### Installing Grafana with Timescale Cloud | ||
|
|
||
| If you're using Timescale Cloud, you can setup a Grafana Metrics Dashboard | ||
| from the **Create Service** flow. | ||
|
|
||
| <img class="main-content__illustration" src="https://assets.iobeam.com/images/docs/screenshots-for-grafana-tutorial/create_service.png" alt="Create a new Grafana service"/> | ||
|
|
||
| #### Installing your own managed instance of Grafana | ||
|
|
||
| You can setup [Grafana][grafana-install] from the Grafana website. Once completed, | ||
| follow the rest of the instructions below. | ||
| # Set up TimescaleDB and Grafana | ||
| This tutorial uses Timescale Cloud to set up your database, and | ||
| to set up Grafana. You can [create a free account][mst-login] to try it out. | ||
|
|
||
| ## Create a new service for Grafana | ||
| You need to sign in to your Timescale Cloud account to create a | ||
| new service to run Grafana. | ||
|
|
||
| ### Procedure: Creating a new service for Grafana | ||
| 1. [Log in to your Timescale Cloud account][mst-login]. By default, you start in the | ||
| `Services` view, showing any services you currently have in your project. | ||
| 1. Click `Create a new service`. | ||
| 1. In the `Select your service` section, click `TimescaleDB Grafana - Metrics | ||
| dashboard`: | ||
| <img class="main-content__illustration" src="https://assets.timescale.com/docs/images/mst-selectservice-grafana.png" alt="Select the Grafana service"/> | ||
| 1. In the `Select your cloud service provider` and `Select your cloud service | ||
| region` sections, choose the provider and region that you prefer, or accept | ||
| the default values. | ||
| 1. In the `Select your service plan` section, click `Dashboard-1`. | ||
| 1. In the `Provide your service name` section, type a name for your new | ||
| service. In this example, we've used `grafana-tutorial`. | ||
| <img class="main-content__illustration" src="https://assets.timescale.com/docs/images/mst-nameservice-grafana.png" alt="Name the Grafana service"/> | ||
| 1. When you are happy with your selections, click `Create Service` to go back | ||
| to the `Services` view while your service is created. The status indicator | ||
| says `Rebuilding` while the service is created. It is ready for you to use | ||
| when the indicator is green and says `Running`. This usually takes a couple | ||
| of minutes, but different clouds can vary. You can click the service name in | ||
| the list to see more information and make changes. | ||
| <img class="main-content__illustration" src="https://assets.timescale.com/docs/images/mst-buildservice-grafana.png" alt="Building the Grafana service"/> | ||
|
|
||
| ## Log in to your Timescale Cloud Grafana service | ||
| When your service is built, you can log and set up your data services. | ||
|
|
||
| ### Logging in to your Timescale Cloud Grafana service | ||
| 1. In the [Timescale Cloud account][mst-login] `Services` view, click the name of your new | ||
| Grafana service. | ||
| 1. On the service details page, take a note of the user name and password for | ||
| your service, and click the link in the `Service URI` field to open Grafana: | ||
| <img class="main-content__illustration" src="https://assets.timescale.com/docs/images/mst-buildservice-grafana.png" alt="Building the Grafana service"/> | ||
| 1. Log in to Grafana with your service credentials. | ||
|
|
||
| ## Connect Grafana to your TimescaleDB instance | ||
| Now you have your Grafana service up and running, you can configure Grafana to | ||
| connect to your TimescaleDB instance. | ||
|
|
||
| ### Connecting Grafana to your TimescaleDB instance | ||
|
|
||
| Next, you need to configure Grafana to connect to your TimescaleDB | ||
| instance. | ||
|
|
||
| Start by selecting 'Add Data Source' and choosing the 'PostgreSQL' option | ||
| in the SQL group: | ||
|
|
||
| <img class="main-content__illustration" src="https://assets.iobeam.com/images/docs/screenshots-for-grafana-tutorial/add_data_source.png" alt="Adding Postgres to Grafana"/> | ||
|
|
||
| In the configuration screen, supply the `Host`, `Database`, `User`, and `Password` for | ||
| your TimescaleDB instance. | ||
|
|
||
| <highlight type="tip"> | ||
| Don't forget to add the port number after your host URI. For example, `hostname.timescaledb.io:19660`. | ||
| </highlight> | ||
|
|
||
| ### Enable TimescaleDB within Grafana | ||
|
|
||
| Since we will be connecting to a TimescaleDB instance for this | ||
| tutorial, we will also want to check the option for 'TimescaleDB' in the | ||
| 'PostgreSQL details' section of the PostgreSQL configuration screen. | ||
|
|
||
| ### Wrapping up | ||
|
|
||
| You should also change the 'Name' of the database to something descriptive. This is | ||
| optional, but will inform others who use your Grafana dashboard what this data source | ||
| contains. | ||
|
|
||
| Once done, click 'Save & Test'. You should receive confirmation that your database | ||
| connection is working. | ||
|
|
||
| <img class="main-content__illustration" src="https://assets.iobeam.com/images/docs/screenshots-for-grafana-tutorial/save_and_test.png" alt="Test your Grafana database connection"/> | ||
|
|
||
| [install-timescale]: /how-to-guides/install-timescaledb/ | ||
| [grafana-install]: https://www.grafana.com | ||
| 1. In Grafana, click `Configuration → Data Sources` in the left menu bar. | ||
| 1. Click `Add Data Source` and choose the `PostgreSQL` option in the SQL group: | ||
| <img class="main-content__illustration" src="https://assets.timescale.com/docs/images/grafana-add-postgresql.png" alt="Adding PostgreSQL to Grafana"/> | ||
| 1. On the data sources configuration page, complete these details: | ||
| * In the `Name` field, type a name for the data source. In this example, | ||
| we used `tsdb-grafana-tutorial`. | ||
| * In the `Host` field, type the Service URI for your service, add a colon | ||
| at the end, and then type the port number. In this example, we used | ||
| `grafana-tutorial-internal-90d0.a.timescaledb.io:443` | ||
| * In the `Database` field, type the name of your Grafana service. In this | ||
| example, we used `grafana-tutorial`. | ||
| * In the `User` field, type the user name for your Grafana service. | ||
| * In the `Password` field, type the password for your Grafana service. | ||
| <img class="main-content__illustration" src="https://assets.timescale.com/docs/images/grafana-configure-postgresql.png" alt="Configure the PostgreSQL data source"/> | ||
| 1. In the `PostgreSQL details` section, in the `TimescaleDB` field, toggle the | ||
| switch on: | ||
| <img class="main-content__illustration" src="https://assets.timescale.com/docs/images/grafana-configure-tsdb.png" alt="Configure PostgreSQL to use TimescaleDB"/> | ||
| 1. Click `Save & Test`. You can confirm your data source is working by clicking | ||
| `Back`, and checking that your service is listed correctly. | ||
|
|
||
| [mst-login]: https://portal.timescale.cloud/login |