BigW Consortium Gitlab

instrumentation.md 4.37 KB
Newer Older
1 2
# Instrumenting Ruby Code

3 4 5 6
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.
7

8 9 10 11 12 13 14 15 16 17
## 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).
18 19
* `instrument_methods`: instruments all public and private class methods of a Module.
* `instrument_instance_methods`: instruments all public and private instance methods of a
20 21 22 23 24 25 26
  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:

27
```ruby
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43
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/metrics.rb`.

### Examples

Instrumenting a single method:

44
```ruby
45 46 47 48 49 50 51
Gitlab::Metrics::Instrumentation.configure do |conf|
  conf.instrument_method(User, :find_by)
end
```

Instrumenting an entire class hierarchy:

52
```ruby
53 54 55 56 57 58 59
Gitlab::Metrics::Instrumentation.configure do |conf|
  conf.instrument_class_hierarchy(ActiveRecord::Base)
end
```

Instrumenting all public class methods:

60
```ruby
61 62 63 64 65 66 67 68 69 70
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:

71
```ruby
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
method = Rugged::TagCollection.instance_method(:[])

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:

```
$ Rugged::TagCollection#[]
```

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})
97 98
  if trans = Gitlab::Metrics::Instrumentation.transaction
    trans.measure_method(#{label.inspect}) { super }
99 100 101 102 103 104 105 106 107 108
  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:
109 110

```ruby
111
Gitlab::Metrics.measure(:foo) do
112 113 114 115
  ...
end
```

116 117 118 119
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.

120
3 values are measured for a block:
121

122 123 124
1. The real time elapsed, stored in NAME_real_time.
2. The CPU time elapsed, stored in NAME_cpu_time.
3. The call count, stored in NAME_call_count.
125

126
Both the real and CPU timings are measured in milliseconds.
127

128 129
Multiple calls to the same block will result in the final values being the sum
of all individual values. Take this code for example:
130 131

```ruby
132 133 134 135
3.times do
  Gitlab::Metrics.measure(:sleep) do
    sleep 1
  end
136 137
end
```
138 139

Here the final value of `sleep_real_time` will be `3`, _not_ `1`.
140 141 142 143 144 145 146 147 148 149 150 151 152 153 154

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