Merge branch 'add-profiler-to-application' into 'master'

Add Gitlab::Profiler for profiling from a console or runner

See merge request gitlab-org/gitlab-ce!16552

2 files changed, 37 insertions, 11 deletions

diff --git a/doc/development/performance.md b/doc/development/performance.md
index e7c5a6ca07a..c4162a05b77 100644
--- a/doc/development/performance.md
+++ b/doc/development/performance.md
@@ -36,7 +36,8 @@ graphs/dashboards.
 
 GitLab provides built-in tools to aid the process of improving performance:
 
-* [Sherlock](profiling.md#sherlock)
+* [Profiling](profiling.md)
+  * [Sherlock](profiling.md#sherlock)
 * [GitLab Performance Monitoring](../administration/monitoring/performance/index.md)
 * [Request Profiling](../administration/monitoring/performance/request_profiling.md)
 * [QueryRecoder](query_recorder.md) for preventing `N+1` regressions
diff --git a/doc/development/profiling.md b/doc/development/profiling.md
index af79353b721..97c997e0568 100644
--- a/doc/development/profiling.md
+++ b/doc/development/profiling.md
@@ -4,6 +4,41 @@ To make it easier to track down performance problems GitLab comes with a set of
 profiling tools, some of these are available by default while others need to be
 explicitly enabled.
 
+## Profiling a URL
+
+There is a `Gitlab::Profiler.profile` method, and corresponding
+`bin/profile-url` script, that enable profiling a GET or POST request to a
+specific URL, either as an anonymous user (the default) or as a specific user.
+
+When using the script, command-line documentation is available by passing no
+arguments.
+
+When using the method in an interactive console session, any changes to the
+application code within that console session will be reflected in the profiler
+output.
+
+For example:
+
+```ruby
+Gitlab::Profiler.profile('/my-user')
+# Returns a RubyProf::Profile for the regular operation of this request
+class UsersController; def show; sleep 100; end; end
+Gitlab::Profiler.profile('/my-user')
+# Returns a RubyProf::Profile where 100 seconds is spent in UsersController#show
+```
+
+Passing a `logger:` keyword argument to `Gitlab::Profiler.profile` will send
+ActiveRecord and ActionController log output to that logger. Further options are
+documented with the method source.
+
+[GitLab-Profiler](https://gitlab.com/gitlab-com/gitlab-profiler) is a project
+that builds on this to add some additional niceties, such as allowing
+configuration with a single Yaml file for multiple URLs, and uploading of the
+profile and log output to S3.
+
+For GitLab.com, you can find the latest results here:
+<http://redash.gitlab.com/dashboard/gitlab-profiler-statistics>
+
 ## Sherlock
 
 Sherlock is a custom profiling tool built into GitLab. Sherlock is _only_
@@ -27,13 +62,3 @@ Bullet will log query problems to both the Rails log as well as the Chrome
 console.
 
 As a follow up to finding `N+1` queries with Bullet, consider writing a [QueryRecoder test](query_recorder.md) to prevent a regression.
-
-## GitLab Profiler
-
-
-[Gitlab-Profiler](https://gitlab.com/gitlab-com/gitlab-profiler) was built to
-help developers understand why specific URLs of their application may be slow
-and to provide hard data that can help reduce load times.
-
-For GitLab.com, you can find the latest results here:
-<http://redash.gitlab.com/dashboard/gitlab-profiler-statistics>