1 files changed, 81 insertions, 0 deletions
diff --git a/doc/development/service_measurement.md b/doc/development/service_measurement.md
new file mode 100644
index 00000000000..bc3f3534cc6
--- /dev/null
+++ b/doc/development/service_measurement.md
@@ -0,0 +1,81 @@
+# GitLab Developers Guide to service measurement
+
+You can enable service measurement in order to debug any slow service's execution time, number of SQL calls, garbage collection stats, memory usage, etc.
+
+## Measuring module
+
+The measuring module is a tool that allows to measure a service's execution, and log:
+
+- Service class name
+- Execution time
+- Number of sql calls
+- Detailed gc stats and diffs
+- RSS memory usage
+- Server worker ID
+
+The measuring module will log these measurements into a structured log called [`service_measurement.log`](../administration/logs.md#service_measurementlog),
+as a single entry for each service execution.
+
+NOTE: **Note:**
+For GitLab.com, `service_measurement.log` is ingested in Elasticsearch and Kibana as part of our monitoring solution.
+
+## How to use it
+
+The measuring module allows you to easily measure and log execution of any service,
+by just prepending `Measurable` in any Service class, on the last line of the file that the class resides in.
+
+For example, to prepend a module into the `DummyService` class, you would use the following approach:
+
+```ruby
+class DummyService
+  def execute
+  # ...
+  end
+end
+
+DummyService.prepend(Measurable)
+```
+
+In case when you are prepending a module from the `EE` namespace with EE features, you need to prepend Measurable after prepending the `EE` module.
+
+This way, `Measurable` will be at the bottom of the ancestor chain, in order to measure execution of `EE` features as well:
+
+```ruby
+class DummyService
+  def execute
+  # ...
+  end
+end
+
+DummyService.prepend_if_ee('EE::DummyService')
+DummyService.prepend(Measurable)
+```
+
+### Log additional attributes
+
+In case you need to log some additional attributes, it is possible to define `extra_attributes_for_measurement` in the service class:
+
+```ruby
+def extra_attributes_for_measurement
+  {
+    project_path: @project.full_path,
+    user: current_user.name
+  }
+end
+```
+
+NOTE: **Note:**
+Once the measurement module is injected in the service, it will be behind generic feature flag.
+In order to actually use it, you need to enable measuring for the desired service by enabling the feature flag.
+
+### Enabling measurement using feature flags
+
+In the following example, the `:gitlab_service_measuring_projects_import_service`
+[feature flag](feature_flags/development.md#enabling-a-feature-flag-in-development) is used to enable the measuring feature
+for `Projects::ImportService`.
+
+From chatops:
+
+```shell
+/chatops run feature set gitlab_service_measuring_projects_import_service true
+```