IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2024-12-30 10:47:30 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Fixed Grafana Fundamentals tutorial to match updated UI (#73168)

Browse Source 
* Update index.md

The word `Configuration` was used to describe an action for getting started, when the actual UI has the word `Administration` and not Configuration. Updated the docs to reflect the actual environment created.

* Update index.md

Updated the tutorial to match the current UI options

* Made copy edits for styling and consistency with Cloud fundamentals tutorial

Made some copy edits to match our style guide and to make this tutorial a bit more consistent with the Cloud version. Also added the step for updating the legend back to the build dashboards section.

* Ran linter

* Edited text to match updated UI

Made edits to match UI behaviour as well as some further style edits.

* Made final copy edits

---------

Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>
Co-authored-by: Isabel Matwawana <isabel.matwawana@grafana.com>
This commit is contained in:
C M 2023-08-16 10:51:53 -07:00 committed by GitHub
parent 451d5a25b2
commit cc1ea31616
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 41 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -116,7 +116,7 @@ Grafana is an open-source platform for monitoring and observability that lets yo
The first thing you see is the Home dashboard, which helps you get started.
To the far left you can see the _sidebar_, a set of quick access icons for navigating Grafana.
In the top left corner, you can see the menu icon. Clicking it will open the _sidebar_, the main menu for navigating Grafana.
## Add a metrics data source
@ -124,11 +124,11 @@ The sample application exposes metrics which are stored in [Prometheus](https://
To be able to visualize the metrics from Prometheus, you first need to add it as a data source in Grafana.
1. In the sidebar, hover over the **Configuration** (gear) icon, and then click **Data sources**.
1. In the sidebar, click **Connections** and then **Data sources**.
1. Click **Add data source**.
1. In the list of data sources, click **Prometheus**.
1. In the URL box, enter **http\://prometheus:9090**.
1. Click **Save & test**.
1. Scroll to the bottom of the page and click **Save & test**.
Prometheus is now available as a data source in Grafana.
@ -138,8 +138,9 @@ Grafana Explore is a workflow for troubleshooting and data exploration. In this
> 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.
1. In the sidebar, click the **Explore** (compass) icon. The Prometheus data source that you added will already be selected.
1. In the **Query editor**, where it says _Enter a PromQL query…_, enter `tns_request_duration_seconds_count` and then press Shift + Enter.
1. Click the menu icon and, in the sidebar, click **Explore**. The Prometheus data source that you added will already be selected.
1. Confirm that you're in code mode by checking the **Builder/Code** toggle at the top right corner of the query panel.
1. In the query editor, where it says _Enter a PromQL query…_, enter `tns_request_duration_seconds_count` and then press Shift + Enter.
A graph appears.
1. In the top right corner, click the dropdown arrow on the **Run Query** button, and then select **5s**. Grafana runs your query and updates the graph every 5 seconds.
@ -147,7 +148,7 @@ Grafana Explore is a workflow for troubleshooting and data exploration. In this
`tns_request_duration_seconds_count` is a _counter_, a type of metric whose value only ever increases. Rather than visualizing the actual value, you can use counters to calculate the _rate of change_, i.e. how fast the value increases.
1. Add the [`rate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate) function to your query to visualize the rate of requests per second. Enter the following in the **Query editor** and then press Shift + Enter.
1. Add the [`rate`](https://prometheus.io/docs/prometheus/latest/querying/functions/#rate) function to your query to visualize the rate of requests per second. Enter the following in the query editor and then press Shift + Enter.
```
rate(tns_request_duration_seconds_count[5m])
@ -165,7 +166,7 @@ Grafana Explore is a workflow for troubleshooting and data exploration. In this
1. Go back to the [sample application](http://localhost:8081) and generate some traffic by adding new links, voting, or just refresh the browser.
1. In the upper-right corner, click the _time picker_, and select **Last 5 minutes**. By zooming in on the last few minutes, it's easier to see when you receive new data.
1. Back in Grafana, in the upper-right corner, click the _time picker_, and select **Last 5 minutes**. By zooming in on the last few minutes, it's easier to see when you receive new data.
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.
@ -173,11 +174,11 @@ Depending on your use case, you might want to group on other labels. Try groupin
Grafana supports log data sources, like [Loki](/oss/loki/). Just like for metrics, you first need to add your data source to Grafana.
1. In the sidebar, hover over the **Configuration** (gear) icon, and then click **Data Sources**.
1. Click **Add data source**.
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. Click **Save & Test** to save your changes.
1. Scroll to the bottom of the page and click **Save & Test** to save your changes.
Loki is now available as a data source in Grafana.
@ -185,9 +186,10 @@ Loki is now available as a data source in Grafana.
Grafana Explore not only lets you make ad-hoc queries for metrics, but lets you explore your logs as well.
1. In the sidebar, click the **Explore** (compass) icon.
1. Click the menu icon and, in the sidebar, click **Explore**.
1. In the data source list at the top, select the **Loki** data source.
1. In the **Query editor**, enter:
1. Confirm that you're in code mode by checking the **Builder/Code** toggle at the top right corner of the query panel.
1. Enter the following in the query editor, and then press Shift + Enter:
```
{filename="/var/log/tns-app.log"}
@ -222,15 +224,18 @@ Dashboards consist of _panels_, each representing a part of the story you want y
Every panel consists of a _query_ and a _visualization_. The query defines _what_ data you want to display, whereas the visualization defines _how_ the data is displayed.
1. In the sidebar, hover over the **Create** (plus sign) icon and then click **Dashboard**.
1. Click **Add new panel**. The Prometheus data source that you added will already be selected.
1. Click the menu icon and, in the sidebar, click **Dashboards**.
1. On the **Dashboards** page, click **New** in top right corner and select **New Dashboard** in the drop-down.
1. Click **+ Add visualization**.
1. In the modal that opens, select the Prometheus data source that you just added.
1. In the **Query** tab below the graph, enter the query from earlier and then press Shift + Enter:
```
sum(rate(tns_request_duration_seconds_count[5m])) by(route)
```
1. In the **Legend** field, enter **{{route}}** to rename the time series in the legend. The graph legend updates when you click outside the field.
1. Click **Options** under the query field to open the panel.
1. In the **Legend** field, select **Custom** and then enter `route` to rename the series in the legend. The graph legend updates when you click outside the field.
1. In the panel editor on the right, under **Panel options**, change the panel title to "Traffic".
1. Click **Apply** in the top-right corner to save the panel and go back to the dashboard view.
1. Click the **Save dashboard** (disk) icon at the top of the dashboard to save your dashboard.
@ -255,6 +260,7 @@ Add a region annotation:
1. Press Ctrl (or Cmd on macOS), then click and drag across the graph to select an area.
1. In **Description**, enter **Performed load tests**.
1. In **Tags**, enter **testing**.
1. Click **Save**.
Manually annotating your dashboard is fine for those single events. For regularly occurring events, such as deploying a new release, Grafana supports querying annotations from one of your data sources. Let's create an annotation using the Loki data source we added earlier.
@ -270,9 +276,9 @@ Manually annotating your dashboard is fine for those single events. For regularl
<!--this add button is gone rn. look into this -->
1. Click **Add**. Grafana displays the Annotations list, with your new annotation.
1. Click the **Go back** arrow 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 so that it's enabled.
1. Click **Apply**. Grafana displays the **Annotations** page, with your new annotation in the list.
1. Click the name of the dashboard in the breadcrumb at the top of the screen to return to your dashboard.
1. At the top of your dashboard, there is now a toggle with the name **Errors** to display the results of the newly created annotation query. The toggle is enabled by default.
The log lines returned by your query are now displayed as annotations in the graph.
@ -288,14 +294,14 @@ Grafana's new alerting platform debuted with Grafana 8. A year later, with Grafa
The most basic alert consists of two parts:
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. Some popular channels include email, webhooks, Slack notifications, and PagerDuty notifications.
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. Some popular channels include email, webhooks, Slack notifications, and PagerDuty notifications.
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.
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.
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
### Create a contact point for Grafana Managed Alerts
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.
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.
1. Browse to [requestbin.com](https://requestbin.com).
1. Under the **Create Request Bin** button, click the **public bin** link.
@ -306,10 +312,10 @@ 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. Click **+ New contact point**.
1. Return to Grafana. Click the menu icon and, in the sidebar, click **Alerting** and then **Contact points**.
1. Click **+ Add contact point**.
1. In **Name**, write **RequestBin**.
1. In **Contact point type**, choose **Webhook**.
1. In the **Integration** dropdown menu, choose **Webhook**.
1. In **Url**, paste the endpoint to your request bin.
1. Click **Test** to send a test alert 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.
@ -321,16 +327,16 @@ We have now created a dummy webhook endpoint and created a new Alerting Contact
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`, and set **Rule type** to **Grafana Managed Alert**. For **Folder** type `fundamentals` and in the box that appears, press **Create: fundamentals**.
1. For **Section 2**, find the **query A** box. Choose your Prometheus datasource and enter the same query that we used in our earlier panel: `sum(rate(tns_request_duration_seconds_count[5m])) by(route)`. Press **Run queries**. You should see some data in the graph.
1. Now scroll down to the **query B** box. For **Operation** choose `Classic condition`. [You can read more about classic and multi-dimensional conditions here](/docs/grafana/latest/alerting/unified-alerting/alerting-rules/create-grafana-managed-rule/#single-and-multi-dimensional-rule). For conditions enter the following: `WHEN last() OF A IS ABOVE 0.2`
1. In **Section 3**, enter `30s` for the **Evaluate every** field. For the purposes of this tutorial, the evaluation interval is intentionally short. This makes it easier to test. In the **for** field, enter `0m`. This setting makes Grafana wait until an alert has fired for a given time before Grafana sends the notification.
1. In **Section 4**, you can add some sample text to your summary message. [Read more about message templating here](/docs/grafana/latest/alerting/unified-alerting/message-templating/).
1. Click **Save and exit** at the top of the page.
1. In Grafana's sidebar, hover over the **Alerting** (bell) icon and then click **Notification policies**.
1. Under **Default policy**, select **...** &rsaquo; **Edit** and change the **Default contact point** to **RequestBin**.
1. In the sidebar, click **Alert rules**.
1. Click **Create alert rule**.
1. In section **1**, name the rule `fundamentals-test`.
1. For section **2**, select **Grafana Managed Alert** as the rule type. Next, find query box **A**. Choose your Prometheus datasource and enter the same query that we used in our earlier panel: `sum(rate(tns_request_duration_seconds_count[5m])) by(route)`. Click **Run queries**. You should see some data in the graph.
1. Now scroll down to query box **B**. Change the operation from **Reduce** to **Classic condition**. [You can read more about classic and multi-dimensional conditions here](/docs/grafana/latest/alerting/unified-alerting/alerting-rules/create-grafana-managed-rule/#single-and-multi-dimensional-rule). For conditions enter the following: `WHEN last() OF A IS ABOVE 0.2`. Delete query **C**.
1. In section **3**, Select **+ Add New** in **Folder** dropdown menu. Name the new folder `fundamentals` and press enter. This will create the folder needed. In **Evaluation Group**, name the group also `fundamentals` for now. In the **for** field, enter `0m`. This setting makes Grafana wait until an alert has fired for a given time before Grafana sends the notification.
1. In section **4**, you can add some sample text to your summary message. [Read more about message templating here](/docs/grafana/latest/alerting/unified-alerting/message-templating/).
1. In the top right corner of the page, click **Save rule and exit**.
1. In the sidebar, click **Notification policies**.
1. Under **Default policy**, click the button with the three dots and select **Edit**. Change the **Default contact point** to **RequestBin**. Click **Update default policy**.
As a system grows, admins can use the **Notification policies** setting to organize and match alert rules to
specific contact points.