1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
---
stage: Monitor
group: Health
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# Instrumenting Ruby code
[GitLab Performance Monitoring](../administration/monitoring/performance/index.md) 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 [Product Analytics](product_analytics/index.md) 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 recursively
instruments 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:
```ruby
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:
```ruby
Gitlab::Metrics::Instrumentation.configure do |conf|
conf.instrument_method(User, :find_by)
end
```
Instrumenting an entire class hierarchy:
```ruby
Gitlab::Metrics::Instrumentation.configure do |conf|
conf.instrument_class_hierarchy(ActiveRecord::Base)
end
```
Instrumenting all public class methods:
```ruby
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:
```ruby
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 prints a result similar to:
```plaintext
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:
```ruby
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 results in the final values being the sum
of all individual values. Take this code for example:
```ruby
3.times do
Gitlab::Metrics.measure(:sleep) do
sleep 1
end
end
```
Here, the final value of `sleep_real_time` is `3`, and 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`.
|
