Document the Performance Bar

Signed-off-by: Rémy Coutable <remy@rymai.me>

5 files changed, 57 insertions, 0 deletions

diff --git a/doc/README.md b/doc/README.md
index fa755852304..68eef1b0886 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -167,6 +167,7 @@ have access to GitLab administration tools and settings.
 - [Operations](administration/operations.md): Keeping GitLab up and running.
 - [Polling](administration/polling.md): Configure how often the GitLab UI polls for updates.
 - [Request Profiling](administration/monitoring/performance/request_profiling.md): Get a detailed profile on slow requests.
+- [Performance Bar](administration/monitoring/performance/performance_bar.md): Get performance information for the current page.
 
 ### Customization
 
diff --git a/doc/administration/monitoring/performance/img/performance_bar.png b/doc/administration/monitoring/performance/img/performance_bar.png
new file mode 100644
index 00000000000..d38293d2ed6
--- /dev/null
+++ b/doc/administration/monitoring/performance/img/performance_bar.png
diff --git a/doc/administration/monitoring/performance/img/performance_bar_line_profiling.png b/doc/administration/monitoring/performance/img/performance_bar_line_profiling.png
new file mode 100644
index 00000000000..7868e2c46d1
--- /dev/null
+++ b/doc/administration/monitoring/performance/img/performance_bar_line_profiling.png
diff --git a/doc/administration/monitoring/performance/img/performance_bar_sql_queries.png b/doc/administration/monitoring/performance/img/performance_bar_sql_queries.png
new file mode 100644
index 00000000000..372ae021f6b
--- /dev/null
+++ b/doc/administration/monitoring/performance/img/performance_bar_sql_queries.png
diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md
new file mode 100644
index 00000000000..ae3da83bde1
--- /dev/null
+++ b/doc/administration/monitoring/performance/performance_bar.md
@@ -0,0 +1,56 @@
+# Performance Bar
+
+>**Note:**
+Available since GitLab 9.4.
+
+A Performance Bar can be displayed, to dig into the performance of a page. When
+activated, it looks as follows:
+
+![Performance Bar](img/performance_bar.png)
+
+It allows you to:
+
+- see the current host serving the page
+- see the timing of the page (backend, frontend)
+- the number of DB queries, the time it took, and the detail of these queries
+![SQL profiling using the Performance Bar](img/performance_bar_sql_queries.png)
+- the number of calls to Redis, and the time it took
+- the number of background jobs created by Sidekiq, and the time it took
+- the number of Ruby GC calls, and the time it took
+- profile the code used to generate the page, line by line
+![Line profiling using the Performance Bar](img/performance_bar_line_profiling.png)
+
+## Enable the Performance Bar
+
+By default, the Performance Bar is disabled. You can enable it either for a
+given feature group or user.
+
+1. Edit `/etc/gitlab/gitlab.rb`
+1. Find the following line, and set it to the group's **full path** that should
+be allowed to use the Performance Bar:
+
+    ```ruby
+    gitlab_rails['performance_bar_allowed_group'] = 'your-org/your-performance-group'
+    ```
+
+1. Save the file and [reconfigure GitLab][reconfigure] for the changes to
+   take effect
+1. The Performance Bar can then be enabled via the
+   [Features API](../../../api/features.md#set-or-create-a-feature) (see below).
+
+### Enable for the `performance_team` feature group
+
+The `performance_team` feature group maps to the group specified by the
+`performance_bar_allowed_group` setting you've set in the previous step.
+
+```
+curl --data "feature_group=performance_team" --data "value=true" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/performance_bar
+```
+
+### Enable for a specific user
+
+```
+curl --data "user=my_username" --data "value=true" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/features/performance_bar
+```
+
+[reconfigure]: ../../restart_gitlab.md#omnibus-gitlab-reconfigure