From e9bc03405359d821d6b62a60c60f37311a12a9a5 Mon Sep 17 00:00:00 2001
From: Amy Qualls <aqualls@gitlab.com>
Date: Fri, 17 Jul 2020 23:47:24 +0000
Subject: [PATCH] Clean up the Grafana Embed page
Update the page to get closer to GitLab tone and style.
---
doc/.vale/gitlab/spelling-exceptions.txt | 1 +
doc/operations/metrics/embed.md | 52 +++++++++++++--------
doc/operations/metrics/embed_grafana.md | 58 +++++++++++++++---------
doc/user/incident_management/index.md | 2 +-
4 files changed, 72 insertions(+), 41 deletions(-)
diff --git a/doc/.vale/gitlab/spelling-exceptions.txt b/doc/.vale/gitlab/spelling-exceptions.txt
index 28da80557eccc..78b5865fdbfa9 100644
--- a/doc/.vale/gitlab/spelling-exceptions.txt
+++ b/doc/.vale/gitlab/spelling-exceptions.txt
@@ -330,6 +330,7 @@ profiler
Prometheus
proxied
proxies
+proxyable
proxying
pseudonymized
pseudonymizer
diff --git a/doc/operations/metrics/embed.md b/doc/operations/metrics/embed.md
index 5ee9b0859b9da..3d089d4fcc9d1 100644
--- a/doc/operations/metrics/embed.md
+++ b/doc/operations/metrics/embed.md
@@ -4,21 +4,25 @@ group: APM
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/#designated-technical-writers
---
-# Embedding metric charts within GitLab Flavored Markdown
+# Embedding metric charts within GitLab-flavored Markdown
+
+You can display metrics charts within
+[GitLab Flavored Markdown](../../user/markdown.md#gitlab-flavored-markdown-gfm)
+fields such as issue or merge request descriptions. The maximum number of embedded
+charts allowed in a GitLab Flavored Markdown field is 100.
+Embedding charts is useful when sharing an application incident or performance
+metrics to others, and you want to have relevant information directly available.
## Embedding GitLab-managed Kubernetes metrics
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/29691) in GitLab 12.2.
-It is possible to display metrics charts within [GitLab Flavored Markdown](../../user/markdown.md#gitlab-flavored-markdown-gfm) fields such as issue or merge request descriptions. The maximum number of embedded charts allowed in a GitLab Flavored Markdown field is 100.
-
-This can be useful if you are sharing an application incident or performance
-metrics to others and want to have relevant information directly available.
-
NOTE: **Note:**
Requires [Kubernetes](../../user/project/integrations/prometheus_library/kubernetes.md) metrics.
-To display metric charts, include a link of the form `https://<root_url>/<project>/-/environments/<environment_id>/metrics`:
+To display metric charts, include a link of the form
+`https://<root_url>/<project>/-/environments/<environment_id>/metrics` in a field
+that supports GitLab-flavored Markdown:
@@ -40,7 +44,7 @@ The following requirements must be met for the metric to unfurl:
- The user must be allowed access to the monitoring dashboard for the environment ([Reporter or higher](../../user/permissions.md)).
- The dashboard must have data within the last 8 hours.
- If all of the above are true, then the metric will unfurl as seen below:
+ If all of the above are true, then the metric unfurls as seen below:
@@ -48,19 +52,25 @@ Metric charts may also be hidden:
-You can open the link directly into your browser for a [detailed view of the data](dashboards/index.md#expand-panel).
+You can open the link directly into your browser for a
+[detailed view of the data](dashboards/index.md#expand-panel).
## Embedding metrics in issue templates
-It is also possible to embed either the default dashboard metrics or individual metrics in issue templates. For charts to render side-by-side, links to the entire metrics dashboard or individual metrics should be separated by either a comma or a space.
+You can also embed either the default dashboard metrics or individual metrics in
+issue templates. For charts to render side-by-side, separate links to the entire metrics
+dashboard or individual metrics by either a comma or a space.
## Embedding metrics based on alerts in incident issues
-For [GitLab-managed alerting rules](alerts.md), the issue will include an embedded chart for the query corresponding to the alert. The chart displays an hour of data surrounding the starting point of the incident, 30 minutes before and after.
+For [GitLab-managed alerting rules](alerts.md), the issue includes an embedded
+chart for the query corresponding to the alert. The chart displays an hour of data
+surrounding the starting point of the incident, 30 minutes before and after.
-For [manually configured Prometheus instances](../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus), a chart corresponding to the query can be included if these requirements are met:
+For [manually configured Prometheus instances](../../user/project/integrations/prometheus.md#manual-configuration-of-prometheus),
+a chart corresponding to the query can be included if these requirements are met:
- The alert corresponds to an environment managed through GitLab.
- The alert corresponds to a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries).
@@ -69,25 +79,31 @@ For [manually configured Prometheus instances](../../user/project/integrations/p
| Attributes | Required | Description |
| ---------- | -------- | ----------- |
| `annotations/gitlab_environment_name` | Yes | Name of the GitLab-managed environment corresponding to the alert |
-| One of `annotations/title`, `annotations/summary`, `labels/alertname` | Yes | Will be used as the chart title |
-| `annotations/gitlab_y_label` | No | Will be used as the chart's y-axis label |
+| One of `annotations/title`, `annotations/summary`, `labels/alertname` | Yes | Used as the chart title |
+| `annotations/gitlab_y_label` | No | Used as the chart's y-axis label |
## Embedding cluster health charts
> - [Introduced](<https://gitlab.com/gitlab-org/gitlab/-/issues/40997>) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9.
> - [Moved](<https://gitlab.com/gitlab-org/gitlab/-/issues/208224>) to GitLab core in 13.2.
-[Cluster Health Metrics](../../user/project/clusters/index.md#visualizing-cluster-health) can also be embedded in [GitLab-flavored Markdown](../../user/markdown.md).
+[Cluster Health Metrics](../../user/project/clusters/index.md#visualizing-cluster-health)
+can also be embedded in [GitLab-flavored Markdown](../../user/markdown.md).
-To embed a metric chart, include a link to that chart in the form `https://<root_url>/<project>/-/cluster/<cluster_id>?<query_params>` anywhere that GitLab-flavored Markdown is supported. To generate and copy a link to the chart, follow the instructions in the [Cluster Health Metric documentation](../../user/project/clusters/index.md#visualizing-cluster-health).
+To embed a metric chart, include a link to that chart in the form
+`https://<root_url>/<project>/-/cluster/<cluster_id>?<query_params>` anywhere that
+GitLab-flavored Markdown is supported. To generate and copy a link to the chart,
+follow the instructions in the
+[Cluster Health Metric documentation](../../user/project/clusters/index.md#visualizing-cluster-health).
The following requirements must be met for the metric to unfurl:
- The `<cluster_id>` must correspond to a real cluster.
- Prometheus must be monitoring the cluster.
- The user must be allowed access to the project cluster metrics.
-- The dashboards must be reporting data on the [Cluster Health Page](../../user/project/clusters/index.md#visualizing-cluster-health)
+- The dashboards must be reporting data on the
+ [Cluster Health Page](../../user/project/clusters/index.md#visualizing-cluster-health)
- If the above requirements are met, then the metric will unfurl as seen below.
+ If the above requirements are met, then the metric unfurls as seen below.
diff --git a/doc/operations/metrics/embed_grafana.md b/doc/operations/metrics/embed_grafana.md
index 427ad86644226..6a5c3de4d4a21 100644
--- a/doc/operations/metrics/embed_grafana.md
+++ b/doc/operations/metrics/embed_grafana.md
@@ -8,24 +8,29 @@ info: To determine the technical writer assigned to the Stage/Group associated w
Grafana metrics can be embedded in [GitLab Flavored Markdown](../../user/markdown.md).
-## Embedding charts via Grafana Rendered Images
+## Embedding charts via Grafana rendered images
-It is possible to embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) charts in issues, as a [direct linked rendered image](https://grafana.com/docs/grafana/latest/reference/share_panel/#direct-link-rendered-image).
-
-The sharing dialog within Grafana provides the link, as highlighted below.
+You can embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html)
+charts in issues as a
+[direct linked rendered image](https://grafana.com/docs/grafana/latest/reference/share_panel/#direct-link-rendered-image).
+The **Direct link rendered image** sharing dialog within Grafana provides the link:
NOTE: **Note:**
-For this embed to display correctly, the Grafana instance must be available to the target user, either as a public dashboard, or on the same network.
+For this embed to display correctly, the Grafana instance must be available to the
+target user, either as a public dashboard or on the same network.
-Copy the link and add an image tag as [inline HTML](../../user/markdown.md#inline-html) in your Markdown. You may tweak the query parameters as required. For instance, removing the `&from=` and `&to=` parameters will give you a live chart. Here is example markup for a live chart from GitLab's public dashboard:
+Copy the link and add an image tag as [inline HTML](../../user/markdown.md#inline-html)
+in your Markdown. You can tweak the query parameters to meet your needs, such as
+removing the `&from=` and `&to=` parameters to display a live chart. Here is example
+markup for a live chart from GitLab's public dashboard:
```html
<img src="https://dashboards.gitlab.com/d/RZmbBr7mk/gitlab-triage?orgId=1&refresh=30s&var-env=gprd&var-environment=gprd&var-prometheus=prometheus-01-inf-gprd&var-prometheus_app=prometheus-app-01-inf-gprd&var-backend=All&var-type=All&var-stage=main&from=1580444107655&to=1580465707655"/>
```
-This will render like so:
+This markup renders a graph of `5xx` errors, like this:
@@ -33,33 +38,42 @@ This will render like so:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31376) in GitLab 12.5.
-Each project can support integration with one Grafana instance. This configuration allows a user to copy a link to a panel in Grafana, then paste it into a GitLab Markdown field. The chart will be rendered in the GitLab chart format.
-
-Prerequisites for embedding from a Grafana instance:
+Each project can support integration with one Grafana instance. This configuration
+enables you to copy a link to a panel in Grafana, then paste it into a GitLab Markdown
+field. The chart renders in the GitLab chart format. To embed charts
+from a Grafana instance, the data source must:
-1. The datasource must be a Prometheus instance.
-1. The datasource must be proxyable, so the HTTP Access setting should be set to `Server`.
+1. Be a Prometheus instance.
+1. Be proxyable, so the HTTP Access setting should be set to `Server`:
-
+ 
## Setting up the Grafana integration
-1. [Generate an Admin-level API Token in Grafana.](https://grafana.com/docs/grafana/latest/http_api/auth/#create-api-token)
-1. In your GitLab project, navigate to **Settings > Operations > Grafana Authentication**.
-1. To enable the integration, check the "Active" checkbox.
-1. For "Grafana URL", enter the base URL of the Grafana instance.
-1. For "API Token", enter the Admin API Token you just generated.
+1. In Grafana, [generate an Admin-level API Token](https://grafana.com/docs/grafana/latest/http_api/auth/#create-api-token).
+1. In your GitLab project, navigate to **{settings}** **Settings > Operations > Grafana Authentication**.
+1. To enable the integration, check the **Active** checkbox.
+1. For **Grafana URL**, enter the base URL of the Grafana instance.
+1. For **API Token**, enter the Admin API Token you just generated.
1. Click **Save Changes**.
## Generating a link to a chart
1. In Grafana, navigate 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 chart.
+1. In the upper-left corner of the page, select a specific value for each variable
+ required for the queries in the chart.
-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 panel instead, GitLab will attempt to embed the first supported panel on the dashboard (if available).
-1. If your Prometheus queries use Grafana's custom template variables, ensure that the "Template variables" option is toggled to **On**. Of Grafana global template variables, only `$__interval`, `$__from`, and `$__to` are currently supported. Toggle **On** the "Current time range" option to specify the time range of the chart. Otherwise, the default range will be the last 8 hours.
+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 panel
+ instead, GitLab attempts to embed the first supported panel on the dashboard (if available).
+1. If your Prometheus queries use Grafana's custom template variables, ensure the
+ **Template variables** option is toggled to **On**. Of Grafana global template
+ variables, only `$__interval`, `$__from`, and `$__to` are supported.
+1. Toggle **On** the **Current time range** option to specify the time range of
+ the chart. Otherwise, the default range is the last 8 hours.
1. Click **Copy** to copy the URL to the clipboard.
-1. In GitLab, paste the URL into a Markdown field and save. The chart will take a few moments to render.
+1. In GitLab, paste the URL into a Markdown field and save. The chart takes a few
+ moments to render.
diff --git a/doc/user/incident_management/index.md b/doc/user/incident_management/index.md
index 996f423e770b8..2efe5a8f790d7 100644
--- a/doc/user/incident_management/index.md
+++ b/doc/user/incident_management/index.md
@@ -64,7 +64,7 @@ in both PagerDuty and GitLab:
1. Activate the integration, and save the changes in GitLab.
-1. Copy the value of **Webhook URL**, as you'll need it in a later step.
+1. Copy the value of **Webhook URL** for use in a later step.
1. Follow the steps described in the
[PagerDuty documentation](https://support.pagerduty.com/docs/webhooks)
to add the webhook URL to a PagerDuty webhook integration.
--
GitLab