Add documentation about changing Grafana dashboards

2 files changed, 28 insertions, 0 deletions

diff --git a/README.md b/README.md
index bfe6269d8..3b2bec458 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,7 @@
   [Want to Contribute?](https://gitlab.com/gitlab-org/gitaly/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Accepting%20Merge%20Requests) |
   [GitLab Gitaly Issues](https://gitlab.com/groups/gitlab-org/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Gitaly) |
   [GitLab Gitaly Merge Requests](https://gitlab.com/groups/gitlab-org/merge_requests?label_name%5B%5D=Gitaly) |
+  [gitlab.com dashboard](https://performance.gitlab.net/dashboard/db/gitaly) |
 
 --------------------------------------------
 
diff --git a/doc/dashboards.md b/doc/dashboards.md
new file mode 100644
index 000000000..cb395917b
--- /dev/null
+++ b/doc/dashboards.md
@@ -0,0 +1,27 @@
+# Editing Gitaly dashboards
+
+Use the Grafana web interface to make changes to dashboards if
+necessary.
+
+**Remember to hit the 'Save' button at the top of the Grafana screen when making changes.**
+
+## Tiled (repeated) dashboards
+
+If you want to make a change across a tiled Grafana dashboard such as
+the [feature request rate
+overview](https://performance.gitlab.net/dashboard/db/gitaly-features-overview),
+then edit the first tile (top left). Its settings get applied to the
+other tiles as well. If you edit any tile other than the first your
+changes will be lost.
+
+## Drop-down values
+
+At the top of most of our Grafana dashboards you find drop-down menus
+for GRPC method names, Prometheus jobs etc. The possible values in these
+drop-downs are defined with Prometheus queries. To see or change these
+queries go into the dashboard's global settings (the gear icon at the
+top of the page) and look in the 'Templating' section. You can then edit
+entries.
+
+Note that Grafana 'templates' use a combination of PromQL and
+Grafana-specific modifiers.