debian-mirror-gitlab/doc/operations/metrics/embed_grafana.md

80 lines
3.6 KiB
Markdown
Raw Normal View History

2020-07-28 23:09:34 +05:30
---
stage: Monitor
2022-04-04 11:22:00 +05:30
group: Respond
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-07-28 23:09:34 +05:30
---
2021-04-17 20:07:23 +05:30
# Embed Grafana panels in Markdown **(FREE)**
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
Grafana panels can be embedded in [GitLab Flavored Markdown](../../user/markdown.md). You can
embed Grafana panels using either:
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
- [Grafana-rendered images](#use-grafana-rendered-images).
- [Grafana API](#use-integration-with-grafana-api).
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
## Use Grafana-rendered images
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
You can embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) panels as a
[direct linked rendered image](https://grafana.com/docs/grafana/latest/reference/share_panel/#direct-link-rendered-image).
Your Grafana instance must:
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
- Be available to the target user, either as a public dashboard or on the same network.
2021-04-29 21:17:54 +05:30
- Have [Grafana Image Renderer](https://grafana.com/grafana/plugins/grafana-image-renderer/) installed.
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
To use Grafana-rendered images:
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
1. Go to the dashboard containing the panel in Grafana.
1. From the panel's menu, select **Share**.
1. Select the **Direct link rendered image** button, which provides the link.
1. Copy the link and add an image tag as [inline HTML](../../user/markdown.md#inline-html) in your
Markdown in the format `<img src="your_link"/>`. You can tweak the query parameters to meet your needs, such as removing the `&from=`
and `&to=` parameters to display a live panel.
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
## Use integration with Grafana API
2020-07-28 23:09:34 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31376) in GitLab 12.5.
2021-04-17 20:07:23 +05:30
Each project can support integration with one Grafana instance. This enables you to copy a link to a
panel in Grafana, then paste it into a GitLab Markdown field. The panel renders in the GitLab panel
format. To embed panels from a Grafana instance, the data source must be:
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
- A Prometheus instance.
- Proxyable, so the **HTTP > Access** setting for the Grafana data source should be set to
**Server (default)**.
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
### Set up Grafana integration
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
To set up the Grafana API in Grafana:
2020-07-28 23:09:34 +05:30
2020-10-24 23:57:45 +05:30
1. In Grafana, [generate an Admin-level API Token](https://grafana.com/docs/grafana/latest/http_api/auth/#create-api-token).
2021-09-04 01:27:46 +05:30
1. In your GitLab project, go to **Settings > Monitor** and expand the **Grafana authentication**
2021-04-17 20:07:23 +05:30
section.
2020-10-24 23:57:45 +05:30
1. To enable the integration, check the **Active** checkbox.
1. For **Grafana URL**, enter the base URL of the Grafana instance.
2021-11-18 22:05:49 +05:30
1. For **API Token**, enter the Administrator API token you just generated.
2020-07-28 23:09:34 +05:30
1. Click **Save Changes**.
2021-04-17 20:07:23 +05:30
### Generate a link to a panel
To generate a link to a panel:
2020-07-28 23:09:34 +05:30
2021-04-17 20:07:23 +05:30
1. In Grafana, go to the dashboard you wish to embed a panel from.
1. In the upper-left corner of the page, select a specific value for each variable required for the
queries in the dashboard.
1. In Grafana click on a panel's title, then click **Share** to open the panel's sharing dialog to
the **Link** tab.
If you click the dashboard's share button instead, GitLab attempts to embed the first supported
panel on the dashboard (if available).
2020-10-24 23:57:45 +05:30
1. If your Prometheus queries use Grafana's custom template variables, ensure the
2021-04-17 20:07:23 +05:30
**Template variables** option is set to on. Only the Grafana global template variables
`$__interval`, `$__from`, and `$__to` are supported.
1. Set the **Current time range** option to on, to specify the time range of the panel. Otherwise,
the default range is the last 8 hours.
1. Select **Copy** to copy the URL to the clipboard.
1. In GitLab, paste the URL into a Markdown field and save. The panel takes a few moments to render.
See the following example of a rendered panel.
![GitLab Rendered Grafana Panel](img/rendered_grafana_embed_v12_5.png)