Merge branch '218566-add-service-measuring-docs' into 'master'

Introduce service measurement docs

Closes #218566

See merge request gitlab-org/gitlab!32678

app/services/concerns/measurable.rb

@@ -4,8 +4,6 @@
 # Example:
 # ```
 #   class DummyService
-#     prepend Measurable
-#
 #     def execute
 #       # ...
 #     end

doc/development/performance.md

@@ -42,6 +42,7 @@ GitLab provides built-in tools to help improve performance and availability:
 - [Request Profiling](../administration/monitoring/performance/request_profiling.md).
 - [QueryRecoder](query_recorder.md) for preventing `N+1` regressions.
 - [Chaos endpoints](chaos_endpoints.md) for testing failure scenarios. Intended mainly for testing availability.
+- [Service measurement](service_measurement.md) for measuring and logging service execution.
 
 GitLab team members can use [GitLab.com's performance monitoring systems](https://about.gitlab.com/handbook/engineering/monitoring/) located at
 <https://dashboards.gitlab.net>, this requires you to log in using your

doc/development/service_measurement.md

+# 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
+```