diff options
Diffstat (limited to 'doc/user/project/integrations')
15 files changed, 152 insertions, 24 deletions
diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index ec43696fdee..62310dd9177 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -1,6 +1,6 @@ # Generic alerts integration **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.3. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13203) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.4. GitLab can accept alerts from any source via a generic webhook receiver. When you set up the generic alerts integration, a unique endpoint will @@ -16,7 +16,7 @@ authored by the GitLab Alert Bot. To set up the generic alerts integration: 1. Navigate to **Settings > Integrations** in a project. -1. Click on **Alert endpoint**. +1. Click on **Alerts endpoint**. 1. Toggle the **Active** alert setting. The `URL` and `Authorization Key` for the webhook configuration can be found there. ## Customizing the payload @@ -37,12 +37,12 @@ Example request: ```sh curl --request POST \ --data '{"title": "Incident title"}' \ - --header "Authorization: Bearer <autorization_key>" \ + --header "Authorization: Bearer <authorization_key>" \ --header "Content-Type: application/json" \ <url> ``` -The `<autorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). +The `<authorization_key>` and `<url>` values can be found when [setting up generic alerts](#setting-up-generic-alerts). Example payload: diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md index 50adb5993e5..c1e6f93de30 100644 --- a/doc/user/project/integrations/gitlab_slack_application.md +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -31,7 +31,7 @@ integration settings. Keep in mind that you need to have the appropriate permissions for your Slack team in order to be able to install a new application, read more in Slack's -docs on [Adding an app to your team][slack-docs]. +docs on [Adding an app to your team](https://slack.com/help/articles/202035138). To enable GitLab's service for your Slack team: @@ -60,6 +60,5 @@ project, you would do: /gitlab gitlab-org/gitlab issue show 1001 ``` -[slack-docs]: https://get.slack.help/hc/en-us/articles/202035138-Adding-apps-to-your-team [slash commands]: ../../../integration/slash_commands.md [slack-manual]: slack_slash_commands.md diff --git a/doc/user/project/integrations/img/embed_metrics_issue_template.png b/doc/user/project/integrations/img/embed_metrics_issue_template.png Binary files differnew file mode 100644 index 00000000000..3c6a243e5c1 --- /dev/null +++ b/doc/user/project/integrations/img/embed_metrics_issue_template.png diff --git a/doc/user/project/integrations/img/grafana_panel_v12_5.png b/doc/user/project/integrations/img/grafana_panel_v12_5.png Binary files differnew file mode 100644 index 00000000000..18c17b910cd --- /dev/null +++ b/doc/user/project/integrations/img/grafana_panel_v12_5.png diff --git a/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png b/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png Binary files differnew file mode 100644 index 00000000000..fae62dd50df --- /dev/null +++ b/doc/user/project/integrations/img/grafana_sharing_dialog_v12_5.png diff --git a/doc/user/project/integrations/img/heatmap_panel_type.png b/doc/user/project/integrations/img/heatmap_panel_type.png Binary files differnew file mode 100644 index 00000000000..a2b3911ec68 --- /dev/null +++ b/doc/user/project/integrations/img/heatmap_panel_type.png diff --git a/doc/user/project/integrations/img/http_proxy_access_v12_5.png b/doc/user/project/integrations/img/http_proxy_access_v12_5.png Binary files differnew file mode 100644 index 00000000000..0036a916a12 --- /dev/null +++ b/doc/user/project/integrations/img/http_proxy_access_v12_5.png diff --git a/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png b/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png Binary files differnew file mode 100644 index 00000000000..5cba6fa9038 --- /dev/null +++ b/doc/user/project/integrations/img/prometheus_dashboard_anomaly_panel_type.png diff --git a/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png b/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png Binary files differnew file mode 100644 index 00000000000..6cabe4193bd --- /dev/null +++ b/doc/user/project/integrations/img/rendered_grafana_embed_v12_5.png diff --git a/doc/user/project/integrations/img/select_query_variables_v12_5.png b/doc/user/project/integrations/img/select_query_variables_v12_5.png Binary files differnew file mode 100644 index 00000000000..23503577327 --- /dev/null +++ b/doc/user/project/integrations/img/select_query_variables_v12_5.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 6d2a0563ec1..874a1092b73 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -59,7 +59,7 @@ When connecting to **Jira Cloud**, which supports authentication via API token, > higher is required. > - GitLab 8.14 introduced a new way to integrate with Jira which greatly simplified > the configuration options you have to enter. If you are using an older version, -> [follow this documentation][jira-repo-old-docs]. +> [follow this documentation](https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable-ee/doc/project_services/jira.md). > - In order to support Oracle's Access Manager, GitLab will send additional cookies > to enable Basic Auth. The cookie being added to each request is `OBBasicAuth` with > a value of `fromDialog`. @@ -205,4 +205,3 @@ authenticate with the Jira site. You will need to log in to your Jira instance and complete the CAPTCHA. [services-templates]: services_templates.md -[jira-repo-old-docs]: https://gitlab.com/gitlab-org/gitlab/blob/8-13-stable/doc/project_services/jira.md diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index e385ee53636..315039f82b3 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -58,7 +58,7 @@ Click on the service links to see further configuration instructions and details ## Push hooks limit -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31009) in GitLab 12.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/17874) in GitLab 12.4. If a single push includes changes to more than three branches or tags, services supported by `push_hooks` and `tag_push_hooks` events won't be executed. diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index d7666d00e76..d3d4afefb59 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -117,7 +117,7 @@ You can view the performance dashboard for an environment by [clicking on the mo Custom metrics can be monitored by adding them on the monitoring dashboard page. Once saved, they will be displayed on the environment performance dashboard provided that either: -- A [connected Kubernetes cluster](../clusters/index.md#adding-and-removing-clusters) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration), or +- A [connected Kubernetes cluster](../clusters/add_remove_clusters.md) with the environment scope of `*` is used and [Prometheus installed on the cluster](#enabling-prometheus-integration) - Prometheus is [manually configured](#manual-configuration-of-prometheus).  @@ -139,7 +139,7 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm - CI_ENVIRONMENT_SLUG - KUBE_NAMESPACE -To specify a variable in a query, enclose it in curly braces with a leading percent. For example: `%{ci_environment_slug}`. +To specify a variable in a query, enclose it in quotation marks with curly braces with a leading percent. For example: `"%{ci_environment_slug}"`. ### Defining custom dashboards per project @@ -211,11 +211,11 @@ The following tables outline the details of expected properties. | Property | Type | Required | Description | | ------ | ------ | ------ | ------- | -| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be `area-chart` or `line-chart` | +| `type` | enum | no, defaults to `area-chart` | Specifies the chart type to use, can be: `area-chart`, `line-chart` or `anomaly-chart`. | | `title` | string | yes | Heading for the panel. | | `y_label` | string | no, but highly encouraged | Y-Axis label for the panel. | | `weight` | number | no, defaults to order in file | Order to appear within the grouping. Lower number means higher priority, which will be higher on the page. Numbers do not need to be consecutive. | -| `metrics` | array | yes | The metrics which should be displayed in the panel. | +| `metrics` | array | yes | The metrics which should be displayed in the panel. Any number of metrics can be displayed when `type` is `area-chart` or `line-chart`, whereas only 3 can be displayed when `type` is `anomaly-chart`. | **Metrics (`metrics`) properties:** @@ -231,20 +231,20 @@ The following tables outline the details of expected properties. The below panel types are supported in monitoring dashboards. -##### Area +##### Area or Line Chart -To add an area panel type to a dashboard, look at the following sample dashboard file: +To add an area chart panel type to a dashboard, look at the following sample dashboard file: ```yaml dashboard: 'Dashboard Title' panel_groups: - group: 'Group Title' panels: - - type: area-chart - title: "Chart Title" + - type: area-chart # or line-chart + title: 'Area Chart Title' y_label: "Y-Axis" metrics: - - id: 10 + - id: area_http_requests_total query_range: 'http_requests_total' label: "Metric of Ages" unit: "count" @@ -255,10 +255,52 @@ Note the following properties: | Property | Type | Required | Description | | ------ | ------ | ------ | ------ | | type | string | no | Type of panel to be rendered. Optional for area panel types | -| query_range | yes | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | +| query_range | string | required | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) |  +##### Anomaly chart + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/16530) in GitLab 12.5. + +To add an anomaly chart panel type to a dashboard, add add a panel with *exactly* 3 metrics. + +The first metric represents the current state, and the second and third metrics represent the upper and lower limit respectively: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - type: anomaly-chart + title: "Chart Title" + y_label: "Y-Axis" + metrics: + - id: anomaly_requests_normal + query_range: 'http_requests_total' + label: "# of Requests" + unit: "count" + metrics: + - id: anomaly_requests_upper_limit + query_range: 10000 + label: "Max # of requests" + unit: "count" + metrics: + - id: anomaly_requests_lower_limit + query_range: 2000 + label: "Min # of requests" + unit: "count" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | required | Must be `anomaly-chart` for anomaly panel types | +| query_range | yes | required | For anomaly panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) in every metric. | + + + ##### Single Stat To add a single stat panel type to a dashboard, look at the following sample dashboard file: @@ -286,6 +328,42 @@ Note the following properties:  +##### Heatmaps + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/30581) in GitLab 12.5. + +To add a heatmap panel type to a dashboard, look at the following sample dashboard file: + +```yaml +dashboard: 'Dashboard Title' +panel_groups: + - group: 'Group Title' + panels: + - title: "Heatmap" + type: "heatmap" + metrics: + - id: 10 + query: 'sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[60m])) by (status_code)' + unit: req/sec + label: "Status code" +``` + +Note the following properties: + +| Property | Type | Required | Description | +| ------ | ------ | ------ | ------ | +| type | string | yes | Type of panel to be rendered. For heatmap panel types, set to `heatmap` | +| query_range | yes | yes | For area panel types, you must use a [range query](https://prometheus.io/docs/prometheus/latest/querying/api/#range-queries) | + + + +### View and edit the source file of a custom dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34779) in GitLab 12.5. + +When viewing a custom dashboard of a project, you can view the original +`.yml` file by clicking on **Edit dashboard** button. + ### Downloading data as CSV Data from Prometheus charts on the metrics dashboard can be downloaded as CSV. @@ -332,9 +410,12 @@ receivers: ... ``` +In order for GitLab to associate your alerts with an [environment](../../../ci/environments.md), you need to configure a `gitlab_environment_name` label on the alerts you set up in Prometheus. The value of this should match the name of your Environment in GitLab. + ### Taking action on incidents **(ULTIMATE)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/4925) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.11. +>- [From GitLab Ultimate 12.5](https://gitlab.com/gitlab-org/gitlab/issues/13401), when GitLab receives a recovery alert, it will automatically close the associated issue. Alerts can be used to trigger actions, like open an issue automatically (enabled by default since `12.1`). To configure the actions: @@ -355,6 +436,8 @@ Once enabled, an issue will be opened automatically when an alert is triggered w - Optional list of attached annotations extracted from `annotations/*` - Alert [GFM](../../markdown.md): GitLab Flavored Markdown from `annotations/gitlab_incident_markdown` +When GitLab receives a **Recovery Alert**, it will automatically close the associated issue. This action will be recorded as a system message on the issue indicated that it was closed automatically by the GitLab Alert bot. + To further customize the issue, you can add labels, mentions, or any other supported [quick action](../quick_actions.md) in the selected issue template, which will apply to all incidents. To limit quick actions or other information to only specific types of alerts, use the `annotations/gitlab_incident_markdown` field. Since [version 12.2](https://gitlab.com/gitlab-org/gitlab-foss/issues/63373), GitLab will tag each incident issue with the `incident` label automatically. If the label does not yet exist, it will be created automatically as well. @@ -389,6 +472,8 @@ Prometheus server. ## Embedding metric charts within GitLab Flavored Markdown +### Embedding GitLab-managed Kubernetes metrics + > [Introduced][ce-29691] in GitLab 12.2. It is possible to display metrics charts within [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). @@ -414,9 +499,19 @@ The following requirements must be met for the metric to unfurl:  -### Embedding live Grafana charts +### 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. + + + +### Embedding Grafana charts -It is also possible to embed live [Grafana](https://docs.gitlab.com/omnibus/settings/grafana.html) charts within issues, as a [Direct Linked Rendered Image](https://grafana.com/docs/reference/sharing/#direct-link-rendered-image). +Grafana metrics can be embedded in [GitLab Flavored Markdown](../../markdown.md). + +#### 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/reference/sharing/#direct-link-rendered-image). The sharing dialog within Grafana provides the link, as highlighted below. @@ -435,6 +530,41 @@ This will render like so: <img src="https://dashboards.gitlab.com/render/d-solo/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&panelId=1247&width=1000&height=300"/> +#### Embedding charts via integration with Grafana HTTP API + +> [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: + +1. The datasource must be a Prometheus instance. +1. The datasource must 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/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. 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 Grafana, click on a panel's title, then click **Share** to open the panel's sharing dialog to the **Link** tab. +1. If your Prometheus queries use Grafana's custom template variables, ensure that "Template variables" and "Current time range" options are toggled to **On**. Of Grafana global template variables, only `$__interval`, `$__from`, and `$__to` are currently supported. +  +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. +  + ## Troubleshooting If the "No data found" screen continues to appear, it could be due to: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index d630956c109..93f6dbb0302 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -30,7 +30,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../clusters/index.md#getting-the-external-endpoint). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 83eac44666c..a1dcb105196 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -30,7 +30,7 @@ For other deployments, there is [some configuration](#manually-setting-up-nginx- ### About managed NGINX Ingress deployments -NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../clusters/index.md#getting-the-external-endpoint). +NGINX Ingress is deployed into the `gitlab-managed-apps` namespace, using the [official Helm chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress). NGINX Ingress will be [externally reachable via the Load Balancer's Endpoint](../../../clusters/applications.md#ingress). NGINX is configured for Prometheus monitoring, by setting: |
