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

85 lines
3.9 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
2022-08-27 11:52:29 +05:30
You can embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) panels as
[a direct link](https://grafana.com/docs/grafana/v7.5/sharing/share-panel/#use-direct-link).
2021-04-17 20:07:23 +05:30
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
2022-08-27 11:52:29 +05:30
1. In Grafana, [generate an Admin-level API Token](https://grafana.com/docs/grafana/next/developers/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.
2022-07-23 23:45:48 +05:30
1. Select **Save Changes**.
2020-07-28 23:09:34 +05:30
2022-08-13 15:12:31 +05:30
NOTE:
If the Grafana integration is enabled, any user with read access to the GitLab
project can query metrics from the Prometheus instance. All requests proxied
through GitLab are authenticated with the same Grafana Administrator API token.
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.
2022-07-23 23:45:48 +05:30
1. In Grafana select a panel's title, then select **Share** to open the panel's sharing dialog to
2021-04-17 20:07:23 +05:30
the **Link** tab.
2022-07-23 23:45:48 +05:30
If you select the dashboard's share button instead, GitLab attempts to embed the first supported
2021-04-17 20:07:23 +05:30
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)