apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

tutorials: sandboxfy grafana fundamentals (#92206)

Browse Source 
* tutorials: sandboxfy grafana fundamentals

* applied feedback

* applied feedback2

* fixed description

* interactives

* ignore new tab instructions

* ignore new tab

* update instructions

* updated alert term / alert isntance

* fix numbering

* adding Lisa's feedback

* changees to fundamentals tutorial

* Fix minor typos and style

* all pretty, no pity

---------

Co-authored-by: Irene Rodriguez <irene.rodriguez@grafana.com>
pull/92743/head
antonio 9 months ago committed by GitHub
parent 6a29e4aecf
commit cf951ab589
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 158 additions and 47 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 205
      docs/sources/tutorials/grafana-fundamentals/index.md

205
docs/sources/tutorials/grafana-fundamentals/index.md
Unescape View File

@ -16,8 +16,15 @@ tags:
- beginner
title: Grafana fundamentals
weight: 10
killercoda:
title: Grafana fundamentals
description: Learn how to use Grafana to set up a monitoring solution for your application. You will explore metrics and logs, build and annotate dashboards, and set up alert rules.
backend:
imageid: ubuntu
---
<!-- INTERACTIVE page intro.md START -->
## Introduction
In this tutorial, you'll learn how to use Grafana to set up a monitoring solution for your application, and:
@ -25,7 +32,9 @@ In this tutorial, you'll learn how to use Grafana to set up a monitoring solutio
- Explore metrics and logs
- Build dashboards
- Annotate dashboards
- Set up alerts
- Set up alert rules
<!-- INTERACTIVE ignore START -->
Alternatively, you can also watch our Grafana for Beginners series where we discuss fundamental concepts to help you get started with Grafana.
@ -42,11 +51,23 @@ Alternatively, you can also watch our Grafana for Beginners series where we disc
- [Docker Compose](https://docs.docker.com/compose/) (included in Docker for Desktop for macOS and Windows)
- [Git](https://git-scm.com/)
### KillerCoda sandbox environment (Alternative)
{{% /class %}}
{{< admonition type="tip" >}}
Alternatively, you can try out this example in our interactive learning environment: [Grafana Fundamentals](https://killercoda.com/grafana-labs/course/grafana/grafana-fundamentals).
If you would prefer to follow along with this tutorial without needing to set up a local environment, you can use the [KillerCoda sandbox environment](https://killercoda.com/grafana-labs/course/full-stack/tutorial-enviroment).
It's a fully configured environment with all the dependencies already installed.
{{% /class %}}
![Interactive](/media/docs/grafana/full-stack-ile.png)
Provide feedback, report bugs, and raise issues in the [Grafana Killercoda repository](https://github.com/grafana/killercoda).
{{< /admonition >}}
<!-- INTERACTIVE ignore END -->
<!-- INTERACTIVE page intro.md END -->
<!-- INTERACTIVE page step1.md START -->
## Set up the sample application
@ -58,19 +79,19 @@ In this step, you'll set up the sample application, as well as supporting servic
1. Clone the [github.com/grafana/tutorial-environment](https://github.com/grafana/tutorial-environment) repository.
```
```bash
git clone https://github.com/grafana/tutorial-environment.git
```
1. Change to the directory where you cloned this repository:
```
```bash
cd tutorial-environment
```
1. Make sure Docker is running:
```
```bash
docker ps
```
@ -78,7 +99,7 @@ In this step, you'll set up the sample application, as well as supporting servic
1. Start the sample application:
```
```bash
docker-compose up -d
```
@ -88,13 +109,13 @@ In this step, you'll set up the sample application, as well as supporting servic
1. Ensure all services are up-and-running:
```
```bash
docker-compose ps
```
In the **State** column, it should say `Up` for all services.
1. Browse to the sample application on [localhost:8081](http://localhost:8081).
1. Browse to the sample application on [http://localhost:8081](http://localhost:8081).
### Grafana News
@ -110,24 +131,49 @@ To add a link:
To vote for a link, click the triangle icon next to the name of the link.
<!-- INTERACTIVE page step1.md END -->
<!-- INTERACTIVE page step2.md START -->
## Open Grafana
Grafana is an open-source platform for monitoring and observability that lets you visualize and explore the state of your systems.
Grafana is an open source platform for monitoring and observability that lets you visualize and explore the state of your systems.
<!-- INTERACTIVE ignore START -->
1. Open a new tab.
1. Browse to [localhost:3000](http://localhost:3000).
1. Browse to [http://localhost:3000](http://localhost:3000).
<!-- INTERACTIVE ignore END -->
{{< docs/ignore >}}
1. Browse to [http://localhost:3000](http://localhost:3000).
{{< /docs/ignore >}}
<!-- INTERACTIVE ignore START -->
{{< admonition type="note" >}}
This demo does not require a login page or credentials. However, if you choose to install Grafana locally, you will need to log in and provide credentials. In that case, the default username and password is `admin`.
{{< /admonition >}}
<!-- INTERACTIVE ignore START -->
{{< docs/ignore >}}
> This demo does not require a login page or credentials. However, if you choose to install Grafana locally, you will need to log in and provide credentials. In that case, the default username and password is `admin`.
> {{< /docs/ignore >}}
The first thing you see is the Home dashboard, which helps you get started.
In the top left corner, you can see the menu icon. Clicking it will open the _sidebar_, the main menu for navigating Grafana.
<!-- INTERACTIVE page step2.md END -->
<!-- INTERACTIVE page step3.md START -->
## Explore your metrics
Grafana Explore is a workflow for troubleshooting and data exploration. In this step, you'll be using Explore to create ad-hoc queries to understand the metrics exposed by the sample application.
Grafana Explore is a workflow for troubleshooting and data exploration. In this step, you'll be using Explore to create ad-hoc queries to understand the metrics exposed by the sample application. Specifically, you'll explore requests received by the sample application.
> Ad-hoc queries are queries that are made interactively, with the purpose of exploring data. An ad-hoc query is commonly followed by another, more specific query.
@ -163,6 +209,10 @@ Grafana Explore is a workflow for troubleshooting and data exploration. In this
Depending on your use case, you might want to group on other labels. Try grouping by other labels, such as `status_code`, by changing the `by(route)` part of the query to `by(status_code)`.
<!-- INTERACTIVE page step3.md END -->
<!-- INTERACTIVE page step4.md START -->
## Add a logging data source
Grafana supports log data sources, like [Loki](/oss/loki/). Just like for metrics, you first need to add your data source to Grafana.
@ -170,11 +220,15 @@ Grafana supports log data sources, like [Loki](/oss/loki/). Just like for metric
1. Click the menu icon and, in the sidebar, click **Connections** and then **Data sources**.
1. Click **+ Add new data source**.
1. In the list of data sources, click **Loki**.
1. In the URL box, enter [http://loki:3100](http://loki:3100).
1. In the URL box, enter `http://loki:3100`
1. Scroll to the bottom of the page and click **Save & Test** to save your changes.
You should see the message "Data source successfully connected." Loki is now available as a data source in Grafana.
<!-- INTERACTIVE page step4.md END -->
<!-- INTERACTIVE page step5.md START -->
## Explore your logs
Grafana Explore not only lets you make ad-hoc queries for metrics, but lets you explore your logs as well.
@ -203,12 +257,16 @@ Let's generate an error, and analyze it with Explore.
{filename="/var/log/tns-app.log"} |= "error"
```
1. Click on the log line that says `level=error msg="empty url"` to see more information about the error.
1. Click the log line that says `level=error msg="empty url"` to see more information about the error.
> **Note:** If you're in Live mode, clicking logs will not show more information about the error. Instead, stop and exit the live stream, then click the log line there.
Logs are helpful for understanding what went wrong. Later in this tutorial, you'll see how you can correlate logs with metrics from Prometheus to better understand the context of the error.
<!-- INTERACTIVE page step5.md END -->
<!-- INTERACTIVE page step6.md START -->
## Build a dashboard
A _dashboard_ gives you an at-a-glance view of your data and lets you track metrics through different visualizations.
@ -236,6 +294,10 @@ Every panel consists of a _query_ and a _visualization_. The query defines _what
{{< figure src="/media/tutorials/grafana-fundamentals-dashboard.png" alt="A panel in a Grafana dashboard" caption="A panel in a Grafana dashboard" >}}
<!-- INTERACTIVE page step6.md END -->
<!-- INTERACTIVE page step7.md START -->
## Annotate events
When things go bad, it often helps if you understand the context in which the failure occurred. Time of last deploy, system changes, or database migration can offer insight into what might have caused an outage. Annotations allow you to represent such events directly on your graphs.
@ -273,9 +335,9 @@ Manually annotating your dashboard is fine for those single events. For regularl
```
1. Click **Apply**. Grafana displays the Annotations list, with your new annotation.
1. Click on your dashboard name to return to your dashboard.
1. Click your dashboard name to return to your dashboard.
1. At the top of your dashboard, there is now a toggle to display the results of the newly created annotation query. Press it if it's not already enabled.
1. Click the **Save dashboard** icon to save the changes.
1. Click the **Save dashboard** (disk) icon to save the changes.
1. To test the changes, go back to the [sample application](http://localhost:8081), post a new link without a URL to generate an error in your browser that says `empty url`.
The log lines returned by your query are now displayed as annotations in the graph.
@ -284,17 +346,33 @@ The log lines returned by your query are now displayed as annotations in the gra
Being able to combine data from multiple data sources in one graph allows you to correlate information from both Prometheus and Loki.
Annotations also work very well alongside alerts. In the next and final section, we will set up an alert for our app `grafana.news` and then we will trigger it. This will provide a quick intro to our new Alerting platform.
Annotations also work very well alongside alert rules. In the next and final section, we will set up an alert rules for our app `grafana.news` and then we will trigger it. This will provide a quick intro to our new Alerting platform.
<!-- INTERACTIVE page step7.md END -->
<!-- INTERACTIVE page step8.md START -->
## Create a Grafana-managed alert rule
Alert rules allow you to identify problems in your system moments after they occur. By quickly identifying unintended changes in your system, you can minimize disruptions to your services.
## Create a Grafana Managed Alert
Grafana's new alerting platform debuted with Grafana 8. A year later, with Grafana 9, it became the default alerting method. In this step we will create a Grafana-managed alert rule. Then we will trigger our new alert rule and send a test message to a dummy endpoint.
Alerts allow you to identify problems in your system moments after they occur. By quickly identifying unintended changes in your system, you can minimize disruptions to your services.
The most basic alert rule consists of two parts:
Grafana's new alerting platform debuted with Grafana 8. A year later, with Grafana 9, it became the default alerting method. In this step we will create a Grafana Managed Alert. Then we will trigger our new alert and send a test message to a dummy endpoint.
1. A _Contact point_ - A Contact point defines how Grafana delivers an alert instance. When the conditions of an _alert rule_ are met, Grafana notifies the contact points, or channels, configured for that alert rule.
The most basic alert consists of two parts:
<!-- INTERACTIVE ignore START -->
1. A _Contact point_ - A Contact point defines how Grafana delivers an alert. When the conditions of an _alert rule_ are met, Grafana notifies the contact points, or channels, configured for that alert.
{{< admonition type="note" >}}
An [alert instance](https://grafana.com/docs/grafana/latest/alerting/fundamentals/#alert-instances) is a specific occurrence that matches a condition defined by an alert rule, such as when the rate of requests for a specific route suddenly increases.
{{< /admonition >}}
<!-- INTERACTIVE ignore END -->
{{< docs/ignore >}}
> An [alert instance](https://grafana.com/docs/grafana/latest/alerting/fundamentals/#alert-instances) is a specific occurrence that matches a condition defined by an alert rule, such as when the rate of requests for a specific route suddenly increases.
> {{< /docs/ignore >}}
Some popular channels include:
@ -304,13 +382,17 @@ The most basic alert consists of two parts:
- [Slack](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/configure-slack/)
- [PagerDuty](https://grafana.com/docs/grafana/latest/alerting/configure-notifications/manage-contact-points/integrations/pager-duty/)
1. An _Alert rule_ - An Alert rule defines one or more _conditions_ that Grafana regularly evaluates. When these evaluations meet the rule's criteria, the alert is triggered.
1. An _Alert rule_ - An Alert rule defines one or more _conditions_ that Grafana regularly evaluates. When these evaluations meet the rule's criteria, the alert rule is triggered.
To begin, let's set up a webhook contact point. Once we have a usable endpoint, we'll write an alert rule and trigger a notification.
### Create a contact point for Grafana Managed Alerts
<!-- INTERACTIVE page step8.md END -->
<!-- INTERACTIVE page step9.md START -->
In this step, we'll set up a new contact point. This contact point will use the _webhooks_ channel. In order to make this work, we also need an endpoint for our webhook channel to receive the alert. We will use [requestbin.com](https://requestbin.com) to quickly set up that test endpoint. This way we can make sure that our alert is actually sending a notification somewhere.
### Create a contact point for Grafana-managed alert rules
In this step, we'll set up a new contact point. This contact point will use the _webhooks_ channel. In order to make this work, we also need an endpoint for our webhook channel to receive the alert notification. We will use [requestbin.com](https://requestbin.com) to quickly set up that test endpoint. This way we can make sure that our alert manager is actually sending a notification somewhere.
1. Browse to [requestbin.com](https://requestbin.com).
1. Under the **Create Request Bin** button, click the link to create a **public bin** instead.
@ -320,26 +402,30 @@ Your Request Bin is now waiting for the first request.
Next, let's configure a Contact Point in Grafana's Alerting UI to send notifications to our Request Bin.
1. Return to Grafana. In Grafana's sidebar, hover over the **Alerting** (bell) icon and then click **Contact points**.
1. Return to Grafana. In Grafana's sidebar, hover over the **Alerting** (bell) icon and then click **Manage Contact points**.
1. Click **+ Add contact point**.
1. In **Name**, write **RequestBin**.
1. In **Integration**, choose **Webhook**.
1. In **URL**, paste the endpoint to your request bin.
1. Click **Test**, and then click **Send test notification** to send a test alert to your request bin.
1. Click **Test**, and then click **Send test notification** to send a test alert notification to your request bin.
1. Navigate back to the Request Bin you created earlier. On the left side, there's now a `POST /` entry. Click it to see what information Grafana sent.
1. Return to Grafana and click **Save contact point**.
We have now created a dummy webhook endpoint and created a new Alerting Contact Point in Grafana. Now we can create an alert rule and link it to this new channel.
### Add an Alert Rule to Grafana
<!-- INTERACTIVE page step9.md END -->
<!-- INTERACTIVE page step10.md START -->
### Add an alert rule to Grafana
Now that Grafana knows how to notify us, it's time to set up an alert rule:
1. In Grafana's sidebar, hover over the **Alerting** (bell) icon and then click **Alert rules**.
1. Click **+ New alert rule**.
1. For **Section 1**, name the rule `fundamentals-test`.
1. For **Section 2**, Find the **query A** box. Choose your Prometheus datasource. Note that the rule type should automatically switch to Grafana-managed alert.
1. For **Section 2**, Find the **query A** box. Choose your Prometheus data source. Note that the rule type should automatically switch to Grafana-managed alert rule.
1. Switch to code mode by checking the Builder/Code toggle.
1. Enter the same Prometheus query that we used in our earlier panel:
@ -347,47 +433,60 @@ Now that Grafana knows how to notify us, it's time to set up an alert rule:
sum(rate(tns_request_duration_seconds_count[5m])) by(route)
```
1. Press **Preview**. You should see some data returned.
1. Keep expressions “B” and "C" as they are. These expressions (Reduce and Threshold, respectively) come by default when creating a new rule. Expression "B", selects the last value of our query “A”, while the Threshold expression "C" will check if the last value from expression "B" is above a specific value. In addition, the Threshold expression is the alert condition by default. Enter `0.2` as threshold value. [You can read more about queries and conditions here](/docs/grafana/latest/alerting/fundamentals/alert-rules/queries-conditions/#expression-queries).
1. In **Section 3**, in Folder, create a new folder, by clicking `New folder` and typing a name for the folder. This folder will contain our alerts. For example: `fundamentals`. Then, click `create`.
1. Scroll down to bottom of section #2 and click the **Preview** button. You should see some data returned.
1. Keep expressions “B” and "C" as they are. These expressions (Reduce and Threshold, respectively) are included by default when creating a new rule. Expression "B", selects the last value of our query “A”, while the Threshold expression "C" will check if the last value from expression "B" is above a specific value. In addition, the Threshold expression is the alert rule condition by default. Enter `0.2` as threshold value. [You can read more about queries and conditions here](/docs/grafana/latest/alerting/fundamentals/alert-rules/queries-conditions/#expression-queries).
1. In **Section 3**, in Folder, create a new folder, by clicking `New folder` and typing a name for the folder. This folder will contain our alert rules. For example: `fundamentals`. Then, click `create`.
1. In the Evaluation group, repeat the above step to create a new one. We will name it `fundamentals` too.
1. Choose an Evaluation interval (how often the alert will be evaluated). For example, every `10s` (10 seconds).
1. Set the pending period. This is the time that a condition has to be met until the alert enters in Firing state and a notification is sent. Enter `0s`. For the purposes of this tutorial, the evaluation interval is intentionally short. This makes it easier to test. This setting makes Grafana wait until an alert has fired for a given time before Grafana sends the notification.
1. Choose an Evaluation interval (how often the alert rule will be evaluated). For example, every `10s` (10 seconds).
1. Set the pending period. This is the time that a condition has to be met until the alert instance enters in Firing state and a notification is sent. Enter `0s`. For the purposes of this tutorial, the evaluation interval is intentionally short. This makes it easier to test. This setting makes Grafana wait until an alert instance has fired for a given time before Grafana sends the notification.
1. In **Section 4**, choose **RequestBin** as the **Contact point**.
1. Click **Save rule and exit** at the top of the page.
### Trigger a Grafana Managed Alert
### Trigger a Grafana-managed alert rule
We have now configured an alert rule and a contact point. Now let's see if we can trigger a Grafana Managed Alert by generating some traffic on our sample application.
We have now configured an alert rule and a contact point. Now let's see if we can trigger a Grafana-managed alert rule by generating some traffic on our sample application.
1. Browse to [localhost:8081](http://localhost:8081).
1. Add a new title and URL, repeatedly click the vote button, or refresh the page to generate a traffic spike.
Once the query `sum(rate(tns_request_duration_seconds_count[5m])) by(route)` returns a value greater than `0.2` Grafana will trigger our alert. Browse to the Request Bin we created earlier and find the sent Grafana alert notification with details and metadata.
Once the query `sum(rate(tns_request_duration_seconds_count[5m])) by(route)` returns a value greater than `0.2` Grafana will trigger our alert rule. Browse to the Request Bin we created earlier and find the sent Grafana alert notification with details and metadata.
<!-- INTERACTIVE ignore START -->
{{< admonition type="note" >}}
The alert may be triggered by the `/metrics` endpoint which is frequently accessed by Grafana when pulling metrics from the application. If this happens, you can increase the **Threshold** value in **Section 2** for testing purposes.
The alert rule may be triggered by the `/metrics` endpoint which is frequently accessed by Grafana when pulling metrics from the application. If this happens, you can increase the **Threshold** value in **Section 2** for testing purposes.
{{< /admonition >}}
### Display Grafana Alerts to your dashboard
<!-- INTERACTIVE ignore START -->
In most cases, it's also valuable to display Grafana Alerts as annotations to your dashboard. Check out the video tutorial below to learn how to display alerting to your dashboard.
{{< docs/ignore >}}
> The alert rule may be triggered by the `/metrics` endpoint which is frequently accessed by Grafana when pulling metrics from the application. If this happens, you can increase the **Threshold** value in **Section 2** for testing purposes.
> {{< /docs/ignore >}}
### Display Grafana-managed alert rules to your dashboard
In most cases, it's also valuable to display Grafana alert instances as annotations to your dashboard. Check out the video tutorial below to learn how to display alerting to your dashboard.
<!-- INTERACTIVE ignore START -->
{{< youtube id="ClLp-iSoaSY" >}}
<!-- INTERACTIVE ignore END -->
Let's see how we can configure this.
1. In Grafana's sidebar, hover over the **Alerting** (bell) icon and then click **Alert rules**.
1. Expand the `fundamentals > fundamentals` folder to view our created alert rule.
1. Click the **Edit** icon and scroll down to **Section 5**.
1. Click the **Link dashboard and panel** button and select the dashboard and panel to which you want the alert to be added as an annotation.
1. Click the **Link dashboard and panel** button and select the dashboard and panel to which you want the alert instance to be added as an annotation.
1. Click **Confirm** and **Save rule and exit** to save all the changes.
1. In Grafana's sidebar, navigate to the dashboard by clicking **Dashboards** and selecting the dashboard you created.
1. To test the changes, follow the steps listed to [trigger a Grafana Managed Alert](#trigger-a-grafana-managed-alert).
1. To test the changes, follow the steps listed to [trigger a Grafana-managed alert rule](#trigger-a-grafana-managed-alert).
You should now see a red, broken heart icon beside the panel name, signifying that the alert has been triggered. An annotation for the alert, represented as a vertical red line, is also displayed.
You should now see a red, broken heart icon beside the panel name, indicating that the alert rule has been triggered. An annotation for the alert instance, represented as a vertical red line, is also displayed.
{{< figure src="/media/tutorials/grafana-alert-on-dashboard.png" alt="A panel in a Grafana dashboard with alerting and annotations configured" caption="Displaying Grafana Alerts on a dashboard" >}}
{{< figure src="/media/tutorials/grafana-alert-on-dashboard.png" alt="A panel in a Grafana dashboard with alerting and annotations configured" caption="Displaying Grafana-managed alert rules on a dashboard" >}}
<!-- INTERACTIVE ignore START -->
@ -405,17 +504,27 @@ Check out our [advanced alerting tutorial](http://grafana.com/tutorials/alerting
{{< /docs/ignore >}}
<!-- INTERACTIVE page step10.md END -->
<!-- INTERACTIVE page finish.md START -->
## Summary
<!-- INTERACTIVE ignore START -->
In this tutorial you learned about fundamental features of Grafana. To do so, we ran several Docker containers on your local machine. When you are ready to clean up this local tutorial environment, run the following command:
```
docker-compose down -v
```
### KillerCoda sandbox environment (completed tutorial)
<!-- INTERACTIVE ignore END -->
Do you want to see the finished result? Check out our [completed KillerCoda sandbox environment](https://killercoda.com/grafana-labs/course/full-stack/tutorial-enviroment-completed) containing the entire demo with dashboards, checks, and data sources configured.
{{< docs/ignore >}}
In this tutorial you learned about fundamental features of Grafana.
{{< /docs/ignore >}}
### Learn more
@ -427,3 +536,5 @@ Check out the links below to continue your learning journey with Grafana's LGTM
- [Alerting Overview](/docs/grafana/latest/alerting/)
- [Alert rules](/docs/grafana/latest/alerting/create-alerts/)
- [Contact points](/docs/grafana/latest/alerting/fundamentals/contact-points/)
<!-- INTERACTIVE page finish.md END -->

Write Preview
Loading…
Cancel
Save