Instrumenting Ruby code
GitLab Performance Monitoring allows instrumenting of both methods and custom blocks of Ruby code. Method instrumentation is the primary form of instrumentation with block-based instrumentation only being used when we want to drill down to specific regions of code within a method.
Please refer to Telemetry if you are tracking product usage patterns.
Instrumenting Methods
Instrumenting methods is done by using the Gitlab::Metrics::Instrumentation
module. This module offers a few different methods that can be used to
instrument code:
-
instrument_method
: instruments a single class method. -
instrument_instance_method
: instruments a single instance method. -
instrument_class_hierarchy
: given a Class this method will recursively instrument all sub-classes (both class and instance methods). -
instrument_methods
: instruments all public and private class methods of a Module. -
instrument_instance_methods
: instruments all public and private instance methods of a Module.
To remove the need for typing the full Gitlab::Metrics::Instrumentation
namespace you can use the configure
class method. This method simply yields
the supplied block while passing Gitlab::Metrics::Instrumentation
as its
argument. An example:
Gitlab::Metrics::Instrumentation.configure do |conf|
conf.instrument_method(Foo, :bar)
conf.instrument_method(Foo, :baz)
end
Using this method is in general preferred over directly calling the various instrumentation methods.
Method instrumentation should be added in the initializer
config/initializers/zz_metrics.rb
.
Examples
Instrumenting a single method:
Gitlab::Metrics::Instrumentation.configure do |conf|
conf.instrument_method(User, :find_by)
end
Instrumenting an entire class hierarchy:
Gitlab::Metrics::Instrumentation.configure do |conf|
conf.instrument_class_hierarchy(ActiveRecord::Base)
end
Instrumenting all public class methods:
Gitlab::Metrics::Instrumentation.configure do |conf|
conf.instrument_methods(User)
end
Checking Instrumented Methods
The easiest way to check if a method has been instrumented is to check its source location. For example:
method = Banzai::Renderer.method(:render)
method.source_location
If the source location points to lib/gitlab/metrics/instrumentation.rb
you
know the method has been instrumented.
If you’re using Pry you can use the $
command to display the source code of a
method (along with its source location), this is easier than running the above
Ruby code. In case of the above snippet you’d run the following:
$ Banzai::Renderer.render
This will print out something along the lines of:
From: /path/to/your/gitlab/lib/gitlab/metrics/instrumentation.rb @ line 148:
Owner: #<Module:0x0055f0865c6d50>
Visibility: public
Number of lines: 21
def #{name}(#{args_signature})
if trans = Gitlab::Metrics::Instrumentation.transaction
trans.measure_method(#{label.inspect}) { super }
else
super
end
end
Instrumenting Ruby Blocks
Measuring blocks of Ruby code is done by calling Gitlab::Metrics.measure
and
passing it a block. For example:
Gitlab::Metrics.measure(:foo) do
...
end
The block is executed and the execution time is stored as a set of fields in the currently running transaction. If no transaction is present the block is yielded without measuring anything.
Three values are measured for a block:
- The real time elapsed, stored in NAME_real_time.
- The CPU time elapsed, stored in NAME_cpu_time.
- The call count, stored in NAME_call_count.
Both the real and CPU timings are measured in milliseconds.
Multiple calls to the same block will result in the final values being the sum of all individual values. Take this code for example:
3.times do
Gitlab::Metrics.measure(:sleep) do
sleep 1
end
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:
Gitlab::Metrics.add_event(:user_login, email: current_user.email)
Event names should be verbs such as push_repository
and remove_branch
.
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc