Merge remote-tracking branch 'upstream/master' into pipeline-emails

* upstream/master: (64 commits)
  Update the 8.11 to 8.12 update documentation to use gitlab-shell 3.5.0
  Update GITLAB_SHELL_VERSION
  Move pushes_since_gc to Redis
  Fix Gitlab::Popen.popen thread-safety issue
  Allow trailing newline in secret base64 data
  Improve .haml-lint.yml, simplify the haml_lint task and remove CHANGELOG entry
  Fix a typo in documentation
  Restore SSH Key title auto-population behavior
  Add test with inactive error use case for 'POST /ci/api/v1/builds/register.json'
  Fix rubocop offences
  Update API documentation
  Update CHANGELOG
  Change response for /ci/api/v1/builds/register.json from 404 to 204
  Document the fact that merge requests from private forks can be checked out locally
  Change method name to #reopenable?
  Improve grammar
  Fix not working test with execute
  Add CHANGELOG
  Improve grammar
  Add #can_reopen? and tests
  ...

1 files changed, 15 insertions, 0 deletions

diff --git a/doc/development/instrumentation.md b/doc/development/instrumentation.md
index c2272ab0a2b..105e2f1242a 100644
--- a/doc/development/instrumentation.md
+++ b/doc/development/instrumentation.md
@@ -137,3 +137,18 @@ end
 ```
 
 Here the final value of `sleep_real_time` will be `3`, _not_ `1`.
+
+## Tracking Custom Events
+
+Besides instrumenting code GitLab Performance Monitoring also supports tracking
+of custom events. This is primarily intended to be used for tracking business
+metrics such as the number of Git pushes, repository imports, and so on.
+
+To track a custom event simply call `Gitlab::Metrics.add_event` passing it an
+event name and a custom set of (optional) tags. For example:
+
+```ruby
+Gitlab::Metrics.add_event(:user_login, email: current_user.email)
+```
+
+Event names should be verbs such as `push_repository` and `remove_branch`.