### Problem to solve We currently do now allow users to add annotations to the charts in our metrics dashboards. This is a feature that is common in other charting tools. ### Intended users * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) ### Further details For example, on the [Grafana Uptime Dashboard](https://dashboards.gitlab.net/d/general-slas/general-slas?orgId=1&from=now-12h&to=now), there is a chart called "Overall SLA over time period - gitlab.com" where we currently cannot fully replicate because we do not have the ability to add annotations to the chart. #### Iteration breakdown **First iteration - MVC** (12.10) - Critical gap Based on the Slack conversation with @marin > Whenever a feature flag is being toggled via our chatops, we query the Grafana API and add the annotations. https://gitlab.com/gitlab-com/chatops/-/blob/3a0b27165e0e2d4dd8c33e6bcd32dc670d72b452/lib/chatops/commands/feature.rb#L279-285 and https://gitlab.com/gitlab-com/chatops/-/blob/3a0b27165e0e2d4dd8c33e6bcd32dc670d72b452/lib/chatops/grafana/annotate.rb for details For MVC, we would support the automatic creation of annotation using webhooks (similar to the way our own Infra team is using annotation in Grafana. This means that we will not have a UI to create annotation manually (third iteration). In addition, the defined Annotations will affect the **entire** dashboard rather than an individual chart (second iteration). **Second iteration** We will implement a FE UI so Users should be able to create an annotation through the UI. Annotations can be scoped to individual charts after defining a panel Id. **Third iteration** Support editing/updating annotations through the UI along with tags support. ## Issues breakdown **First iteration** https://gitlab.com/groups/gitlab-org/-/epics/3046 1. Backend: Basic Implement of annotations CRUD. https://gitlab.com/gitlab-org/gitlab/-/issues/211329 1. Backend: Add endpoint for webhooks to consume and create annotations https://gitlab.com/gitlab-org/gitlab/-/issues/211460 1. Backend: Expose an endpoint to fetch all annotations. https://gitlab.com/gitlab-org/gitlab/-/issues/211330 1. Frontend: Fetch annotations for monitoring dashboard and display on all charts. https://gitlab.com/gitlab-org/gitlab/-/issues/211418 1. Discuss: Determine the best ways to store annotation tags. https://gitlab.com/gitlab-org/gitlab/-/issues/211426 **Second iteration** https://gitlab.com/groups/gitlab-org/-/epics/3047 1. Backend: Expose an endpoint to perform CUD operations on annotations. https://gitlab.com/gitlab-org/gitlab/-/issues/211461 1. Design: Range annotation on metrics chart. https://gitlab.com/gitlab-org/gitlab/-/issues/214373 1. Spike: Explore eCharts APIs to support annotation ranges for monitoring charts. https://gitlab.com/gitlab-org/gitlab/-/issues/212910 1. Backend: Update annotations GraphQL API to support CUD operations https://gitlab.com/gitlab-org/gitlab/-/issues/211461 **Third iteration** https://gitlab.com/groups/gitlab-org/-/epics/3048 1. Frontend: Create a UI to create annotations 1. Clicking on a monitoring chart should show popover menu to create annotation (https://gitlab.com/gitlab-org/gitlab/-/issues/211419) 1. Display a form to create annotation from the chart popover menu (https://gitlab.com/gitlab-org/gitlab/-/issues/211425) 1. Backend: Basic implementation of annotation tags CRUD. https://gitlab.com/gitlab-org/gitlab/-/issues/211429 1. Frontend: Fetch annotations for a panel https://gitlab.com/gitlab-org/gitlab/-/issues/211432 1. Backend: Create a reaper job to remove all annotations older than 14 days. https://gitlab.com/gitlab-org/gitlab/-/issues/211433 1. Frontend: Edit/update/delete annotations through UI. More focus on tags editing and creating. https://gitlab.com/gitlab-org/gitlab/-/issues/211434 ### Proposed Solution [DESIGN SPECS](https://gitlab-org.gitlab.io/gitlab-design/hosted/nadia/gl%23205029-metrics-chart-annotations-spec-previews/) **First iteration** The user can see annotations in the chart and see each annotation details on hover. | Annotation indicator on a chart | Annotation on hover | | ------ | ------ | |  |  | Annotations can display labels. | Annotation with labels | | ------ | |  | In further iterations, annotations can be added via the chart UI, as well as edited or deleted on the spot. **Second iteration** | Annotation with an edit button | | ------ | |  | | Hover over a chart, see the timestamp and value | Click to view the menu | Add annotation | | ------ | ------ | ------ | |  |  |  | ### Permissions and Security ### Documentation We should add docs for the metrics dashboards. ### Availability & Testing ### What does success look like, and how can we measure that? ### What is the type of buyer? ### Links / references