Merge branch 'annotations-create-api-docs' into 'master'

Documentation for API endpoint creating Annotations

See merge request gitlab-org/gitlab!29368

doc/api/api_resources.md

@@ -130,6 +130,7 @@ The following API resources are available outside of project and group contexts
 | [License](license.md) **(CORE ONLY)**              | `/license`                                                              |
 | [Markdown](markdown.md)                            | `/markdown`                                                             |
 | [Merge requests](merge_requests.md)                | `/merge_requests` (also available for groups and projects)              |
+| [Metrics dashboard annotations](metrics_dashboard_annotations.md)    | `/environments/:id/metrics_dashboard/annotations`     |
 | [Namespaces](namespaces.md)                        | `/namespaces`                                                           |
 | [Notification settings](notification_settings.md)  | `/notification_settings` (also available for groups and projects)       |
 | [Pages domains](pages_domains.md)                  | `/pages/domains` (also available for projects)                          |

doc/api/metrics_dashboard_annotations.md

+# Dashboard annotations API
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag.
+
+Metrics dashboard annotations allow you to indicate events on your graphs at a single point in time or over a timespan.
+
+## Enable the metrics dashboard annotations API
+
+The `:metrics_dashboard_annotations` feature flag is disabled by default.
+To turn on this API, ask a GitLab administrator with Rails console
+access to run the following command:
+
+```ruby
+Feature.enable(:metrics_dashboard_annotations)
+```
+
+## Create a new annotation
+
+```plaintext
+POST /environments/:id/metrics_dashboard/annotations/
+```
+
+Parameters:
+
+| Attribute      | Type           | Required | Description                                                                  |
+|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
+| `dashboard_path` | string        | yes      | ID of the dashboard which needs to be annotated.   |
+| `starting_at` | string        | yes      | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking start point of annotation.   |
+| `ending_at` | string        | no      | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z`. Timestamp marking end point of annotation. When not supplied annotation will be displayed as single event at start point.  |
+| `description` | string        | yes      | Description of the annotation.  |
+
+```shell
+curl --header 'Private-Token: <your_access_token>' https://gitlab.example.com/api/v4/environments/1/metrics_dashboard/annotations \
+ --data-urlencode "dashboard_path=.gitlab/dashboards/custom_metrics.yml" \
+ --data-urlencode "starting_at=2016-03-11T03:45:40Z" \
+ --data-urlencode "description=annotation description"
+```
+
+Example Response:
+
+```json
+{
+  "id": 4,
+  "starting_at": "2016-04-08T03:45:40.000Z",
+  "ending_at": null,
+  "dashboard_path": ".gitlab/dashboards/custom_metrics.yml",
+  "description": "annotation description",
+  "environment_id": 1,
+  "cluster_id": null
+}
+```

doc/user/permissions.md

@@ -86,8 +86,11 @@ The following table depicts the various user permission levels in a project.
 | View Error Tracking list                          |         | ✓          | ✓           | ✓        | ✓      |
 | Create new merge request                          |         | ✓          | ✓           | ✓        | ✓      |
 | View requirements **(ULTIMATE)**                  |         | ✓          | ✓           | ✓        | ✓      |
+| View metrics dashboard annotations                |         | ✓          | ✓           | ✓        | ✓      |
 | Pull [packages](packages/index.md)                |         | ✓          | ✓           | ✓        | ✓      |
 | Publish [packages](packages/index.md)             |         |            | ✓           | ✓        | ✓      |
+| Pull from [Conan repository](packages/conan_repository/index.md), [Maven repository](packages/maven_repository/index.md), or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** |         | ✓          | ✓           | ✓        | ✓      |
+| Publish to [Conan repository](packages/conan_repository/index.md), [Maven repository](packages/maven_repository/index.md), or [NPM registry](packages/npm_registry/index.md) **(PREMIUM)** |         |            | ✓           | ✓        | ✓      |
 | Upload [Design Management](project/issues/design_management.md) files |  |  | ✓        | ✓        | ✓      |
 | Create/edit/delete [Releases](project/releases/index.md)|   |            | ✓           | ✓        | ✓      |
 | Create new branches                               |         |            | ✓           | ✓        | ✓      |
@@ -120,6 +123,7 @@ The following table depicts the various user permission levels in a project.
 | Rewrite/remove Git tags                           |         |            | ✓           | ✓        | ✓      |
 | Manage Feature Flags **(PREMIUM)**                |         |            | ✓           | ✓        | ✓      |
 | Manage requirements **(ULTIMATE)**                |         |            | ✓           | ✓        | ✓      |
+| Create/edit/delete metrics dashboard annotations  |         |            | ✓           | ✓        | ✓      |
 | Use environment terminals                         |         |            |             | ✓        | ✓      |
 | Run Web IDE's Interactive Web Terminals **(ULTIMATE ONLY)** |     |      |             | ✓        | ✓      |
 | Add new team members                              |         |            |             | ✓        | ✓      |
@@ -224,10 +228,12 @@ group.
 | Create/edit group epic **(ULTIMATE)**                  |       | ✓        | ✓         | ✓          | ✓     |
 | Manage group labels                                    |       | ✓        | ✓         | ✓          | ✓     |
 | See a container registry                               |       | ✓        | ✓         | ✓          | ✓     |
+| View metrics dashboard annotations                     |       | ✓        | ✓         | ✓          | ✓     |
 | Create project in group                                |       |          | ✓ (3)     | ✓ (3)      | ✓ (3) |
 | Create/edit/delete group milestones                    |       |          | ✓         | ✓          | ✓     |
 | Enable/disable a dependency proxy **(PREMIUM)**        |       |          | ✓         | ✓          | ✓     |
 | Use security dashboard **(ULTIMATE)**                  |       |          | ✓         | ✓          | ✓     |
+| Create/edit/delete metrics dashboard annotations       |       |          | ✓         | ✓          | ✓     |
 | View/manage group-level Kubernetes cluster             |       |          |           | ✓          | ✓     |
 | Create subgroup                                        |       |          |           | ✓ (1)      | ✓     |
 | Edit epic comments (posted by any user) **(ULTIMATE)** |       |          |           | ✓ (2)      | ✓ (2) |

doc/user/project/integrations/prometheus.md

@@ -630,6 +630,20 @@ The options are:
 - [Copy link to chart](#embedding-gitlab-managed-kubernetes-metrics)
 - [Alerts](#setting-up-alerts-for-prometheus-metrics)
 
+### Dashboard Annotations
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/211330) in GitLab 12.10 (enabled by feature flag `metrics_dashboard_annotations`).
+
+You can use **Metrics Dashboard Annotations** to mark any important events on
+every metrics dashboard by adding annotations to it. While viewing a dashboard,
+annotation entries assigned to the selected time range will be automatically
+fetched and displayed on every chart within that dashboard. On mouse hover, each
+annotation presents additional details, including the exact time of an event and
+its description.
+
+You can create annotations by making requests to the
+[Metrics dashboard annotations API](../../../api/metrics_dashboard_annotations.md)
+
 ### View Logs **(ULTIMATE)**
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/122013) in GitLab 12.8.