Commit ffb09b69 authored by Ezekiel Kigbo's avatar Ezekiel Kigbo

Merge branch 'eread/refactor-embedded-grafana-panels' into 'master'

Refactor docs and UI for embedding Grafana panels

See merge request gitlab-org/gitlab!55567
parents fa7685ef c5d01326
<script> <script>
import { GlButton, GlFormGroup, GlFormInput, GlFormCheckbox, GlIcon } from '@gitlab/ui'; import { GlButton, GlFormGroup, GlFormInput, GlFormCheckbox, GlIcon, GlLink } from '@gitlab/ui';
import { mapState, mapActions } from 'vuex'; import { mapState, mapActions } from 'vuex';
import { helpPagePath } from '~/helpers/help_page_helper';
export default { export default {
components: { components: {
...@@ -9,9 +10,15 @@ export default { ...@@ -9,9 +10,15 @@ export default {
GlFormGroup, GlFormGroup,
GlFormInput, GlFormInput,
GlIcon, GlIcon,
GlLink,
}, },
data() { data() {
return { placeholderUrl: 'https://my-url.grafana.net/' }; return {
helpUrl: helpPagePath('operations/metrics/embed_grafana', {
anchor: 'use-integration-with-grafana-api',
}),
placeholderUrl: 'https://my-grafana.example.com/',
};
}, },
computed: { computed: {
...mapState(['operationsSettingsEndpoint', 'grafanaToken', 'grafanaUrl', 'grafanaEnabled']), ...mapState(['operationsSettingsEndpoint', 'grafanaToken', 'grafanaUrl', 'grafanaEnabled']),
...@@ -59,7 +66,12 @@ export default { ...@@ -59,7 +66,12 @@ export default {
</h4> </h4>
<gl-button class="js-settings-toggle">{{ __('Expand') }}</gl-button> <gl-button class="js-settings-toggle">{{ __('Expand') }}</gl-button>
<p class="js-section-sub-header"> <p class="js-section-sub-header">
{{ s__('GrafanaIntegration|Embed Grafana charts in GitLab issues.') }} {{
s__(
'GrafanaIntegration|Set up Grafana authentication to embed Grafana panels in GitLab Flavored Markdown.',
)
}}
<gl-link :href="helpUrl">{{ __('Learn more.') }}</gl-link>
</p> </p>
</div> </div>
<div class="settings-content"> <div class="settings-content">
...@@ -78,22 +90,22 @@ export default { ...@@ -78,22 +90,22 @@ export default {
> >
<gl-form-input id="grafana-url" v-model="localGrafanaUrl" :placeholder="placeholderUrl" /> <gl-form-input id="grafana-url" v-model="localGrafanaUrl" :placeholder="placeholderUrl" />
</gl-form-group> </gl-form-group>
<gl-form-group :label="s__('GrafanaIntegration|API Token')" label-for="grafana-token"> <gl-form-group :label="s__('GrafanaIntegration|API token')" label-for="grafana-token">
<gl-form-input id="grafana-token" v-model="localGrafanaToken" /> <gl-form-input id="grafana-token" v-model="localGrafanaToken" />
<p class="form-text text-muted"> <p class="form-text text-muted">
{{ s__('GrafanaIntegration|Enter the Grafana API Token.') }} {{ s__('GrafanaIntegration|Enter the Grafana API token.') }}
<a <a
href="https://grafana.com/docs/http_api/auth/#create-api-token" href="https://grafana.com/docs/http_api/auth/#create-api-token"
target="_blank" target="_blank"
rel="noopener noreferrer" rel="noopener noreferrer"
> >
{{ __('More information') }} {{ __('More information.') }}
<gl-icon name="external-link" class="vertical-align-middle" /> <gl-icon name="external-link" class="vertical-align-middle" />
</a> </a>
</p> </p>
</gl-form-group> </gl-form-group>
<gl-button variant="success" category="primary" @click="updateGrafanaIntegration"> <gl-button variant="success" category="primary" @click="updateGrafanaIntegration">
{{ __('Save Changes') }} {{ __('Save changes') }}
</gl-button> </gl-button>
</form> </form>
</div> </div>
......
---
title: Refactor docs and UI for embedding Grafana panels
merge_request: 55567
author:
type: other
...@@ -4,75 +4,76 @@ group: Health ...@@ -4,75 +4,76 @@ group: Health
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 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
--- ---
# Embedding Grafana charts **(FREE)** # Embed Grafana panels in Markdown **(FREE)**
Grafana metrics can be embedded in [GitLab Flavored Markdown](../../user/markdown.md). Grafana panels can be embedded in [GitLab Flavored Markdown](../../user/markdown.md). You can
embed Grafana panels using either:
## Embedding charts via Grafana rendered images - [Grafana-rendered images](#use-grafana-rendered-images).
- [Grafana API](#use-integration-with-grafana-api).
You can embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) ## Use Grafana-rendered images
charts in issues as a
[direct linked rendered image](https://grafana.com/docs/grafana/latest/reference/share_panel/#direct-link-rendered-image). Your Grafana instance must be available to the
target user, either as a public dashboard or on the same network. The
**Direct link rendered image** sharing dialog within Grafana provides the link:
![Grafana Direct Linked Rendered Image](img/grafana_live_embed.png) 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:
For this embed to display correctly, the - Be available to the target user, either as a public dashboard or on the same network.
- Have [Grafana Image Renderer](https://grafana.com/grafana/plugins/grafana-image-renderer) installed.
Copy the link and add an image tag as [inline HTML](../../user/markdown.md#inline-html) To use Grafana-rendered images:
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 a GitLab public dashboard:
```html 1. Go to the dashboard containing the panel in Grafana.
<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"/> 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.
This markup renders a graph of `5xx` errors, like this: ## Use integration with Grafana API
![Grafana dashboard embedded preview](img/grafana_embedded.png)
## Embedding charts via integration with Grafana HTTP API
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31376) in GitLab 12.5. > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/31376) in GitLab 12.5.
Each project can support integration with one Grafana instance. This configuration Each project can support integration with one Grafana instance. This enables you to copy a link to a
enables you to copy a link to a panel in Grafana, then paste it into a GitLab Markdown panel in Grafana, then paste it into a GitLab Markdown field. The panel renders in the GitLab panel
field. The chart renders in the GitLab chart format. To embed charts format. To embed panels from a Grafana instance, the data source must be:
from a Grafana instance, the data source must:
1. Be a Prometheus instance. - A Prometheus instance.
1. Be proxyable, so the HTTP Access setting should be set to `Server`: - Proxyable, so the **HTTP > Access** setting for the Grafana data source should be set to
**Server (default)**.
![HTTP Proxy Access](img/http_proxy_access_v12_5.png) ### Set up Grafana integration
## Setting up the Grafana integration To set up the Grafana API in Grafana:
1. In Grafana, [generate an Admin-level API Token](https://grafana.com/docs/grafana/latest/http_api/auth/#create-api-token). 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 > Operations > Grafana Authentication**. 1. In your GitLab project, go to **Settings > Operations** and expand the **Grafana authentication**
section.
1. To enable the integration, check the **Active** checkbox. 1. To enable the integration, check the **Active** checkbox.
1. For **Grafana URL**, enter the base URL of the Grafana instance. 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. For **API Token**, enter the Admin API token you just generated.
1. Click **Save Changes**. 1. Click **Save Changes**.
## Generating a link to a chart ### Generate a link to a panel
To generate a link to a panel:
1. In Grafana, navigate to the dashboard you wish to embed a panel from. 1. In Grafana, go to the dashboard you wish to embed a panel from.
![Grafana Metric Panel](img/grafana_panel_v12_5.png) 1. In the upper-left corner of the page, select a specific value for each variable required for the
1. In the upper-left corner of the page, select a specific value for each variable queries in the dashboard.
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
![Select Query Variables](img/select_query_variables_v12_5.png) the **Link** tab.
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 If you click the dashboard's share button instead, GitLab attempts to embed the first supported
instead, GitLab attempts to embed the first supported panel on the dashboard (if available). panel on the dashboard (if available).
1. If your Prometheus queries use Grafana's custom template variables, ensure the 1. If your Prometheus queries use Grafana's custom template variables, ensure the
**Template variables** option is toggled to **On**. Of Grafana global template **Template variables** option is set to on. Only the Grafana global template variables
variables, only `$__interval`, `$__from`, and `$__to` are supported. `$__interval`, `$__from`, and `$__to` are supported.
1. Toggle **On** the **Current time range** option to specify the time range of 1. Set the **Current time range** option to on, to specify the time range of the panel. Otherwise,
the chart. Otherwise, the default range is the last 8 hours. the default range is the last 8 hours.
![Grafana Sharing Dialog](img/grafana_sharing_dialog_v12_5.png) 1. Select **Copy** to copy the URL to the clipboard.
1. Click **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.
1. In GitLab, paste the URL into a Markdown field and save. The chart 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)
![GitLab Rendered Grafana Panel](img/rendered_grafana_embed_v12_5.png)
...@@ -14421,16 +14421,13 @@ msgstr "" ...@@ -14421,16 +14421,13 @@ msgstr ""
msgid "Grafana response contains invalid json" msgid "Grafana response contains invalid json"
msgstr "" msgstr ""
msgid "GrafanaIntegration|API Token" msgid "GrafanaIntegration|API token"
msgstr "" msgstr ""
msgid "GrafanaIntegration|Active" msgid "GrafanaIntegration|Active"
msgstr "" msgstr ""
msgid "GrafanaIntegration|Embed Grafana charts in GitLab issues." msgid "GrafanaIntegration|Enter the Grafana API token."
msgstr ""
msgid "GrafanaIntegration|Enter the Grafana API Token."
msgstr "" msgstr ""
msgid "GrafanaIntegration|Enter the base URL of the Grafana instance." msgid "GrafanaIntegration|Enter the base URL of the Grafana instance."
...@@ -14442,6 +14439,9 @@ msgstr "" ...@@ -14442,6 +14439,9 @@ msgstr ""
msgid "GrafanaIntegration|Grafana authentication" msgid "GrafanaIntegration|Grafana authentication"
msgstr "" msgstr ""
msgid "GrafanaIntegration|Set up Grafana authentication to embed Grafana panels in GitLab Flavored Markdown."
msgstr ""
msgid "Grant access" msgid "Grant access"
msgstr "" msgstr ""
......
...@@ -162,13 +162,13 @@ RSpec.describe 'Projects > Settings > For a forked project', :js do ...@@ -162,13 +162,13 @@ RSpec.describe 'Projects > Settings > For a forked project', :js do
end end
expect(page).to have_content('Grafana URL') expect(page).to have_content('Grafana URL')
expect(page).to have_content('API Token') expect(page).to have_content('API token')
expect(page).to have_button('Save Changes') expect(page).to have_button('Save changes')
fill_in('grafana-url', with: 'http://gitlab-test.grafana.net') fill_in('grafana-url', with: 'http://gitlab-test.grafana.net')
fill_in('grafana-token', with: 'token') fill_in('grafana-token', with: 'token')
click_button('Save Changes') click_button('Save changes')
wait_for_requests wait_for_requests
......
...@@ -31,8 +31,11 @@ exports[`grafana integration component default state to match the default snapsh ...@@ -31,8 +31,11 @@ exports[`grafana integration component default state to match the default snapsh
class="js-section-sub-header" class="js-section-sub-header"
> >
Embed Grafana charts in GitLab issues. Set up Grafana authentication to embed Grafana panels in GitLab Flavored Markdown.
<gl-link-stub>
Learn more.
</gl-link-stub>
</p> </p>
</div> </div>
...@@ -56,13 +59,13 @@ exports[`grafana integration component default state to match the default snapsh ...@@ -56,13 +59,13 @@ exports[`grafana integration component default state to match the default snapsh
> >
<gl-form-input-stub <gl-form-input-stub
id="grafana-url" id="grafana-url"
placeholder="https://my-url.grafana.net/" placeholder="https://my-grafana.example.com/"
value="http://test.host" value="http://test.host"
/> />
</gl-form-group-stub> </gl-form-group-stub>
<gl-form-group-stub <gl-form-group-stub
label="API Token" label="API token"
label-for="grafana-token" label-for="grafana-token"
> >
<gl-form-input-stub <gl-form-input-stub
...@@ -74,7 +77,7 @@ exports[`grafana integration component default state to match the default snapsh ...@@ -74,7 +77,7 @@ exports[`grafana integration component default state to match the default snapsh
class="form-text text-muted" class="form-text text-muted"
> >
Enter the Grafana API Token. Enter the Grafana API token.
<a <a
href="https://grafana.com/docs/http_api/auth/#create-api-token" href="https://grafana.com/docs/http_api/auth/#create-api-token"
...@@ -82,7 +85,7 @@ exports[`grafana integration component default state to match the default snapsh ...@@ -82,7 +85,7 @@ exports[`grafana integration component default state to match the default snapsh
target="_blank" target="_blank"
> >
More information More information.
<gl-icon-stub <gl-icon-stub
class="vertical-align-middle" class="vertical-align-middle"
...@@ -101,7 +104,7 @@ exports[`grafana integration component default state to match the default snapsh ...@@ -101,7 +104,7 @@ exports[`grafana integration component default state to match the default snapsh
variant="success" variant="success"
> >
Save Changes Save changes
</gl-button-stub> </gl-button-stub>
</form> </form>
......
...@@ -62,7 +62,7 @@ describe('grafana integration component', () => { ...@@ -62,7 +62,7 @@ describe('grafana integration component', () => {
wrapper = shallowMount(GrafanaIntegration, { store }); wrapper = shallowMount(GrafanaIntegration, { store });
expect(wrapper.find('.js-section-sub-header').text()).toContain( expect(wrapper.find('.js-section-sub-header').text()).toContain(
'Embed Grafana charts in GitLab issues.', 'Set up Grafana authentication to embed Grafana panels in GitLab Flavored Markdown.\n Learn more.',
); );
}); });
}); });
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment