instana 1.10.1-java
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.codeclimate.yml +23 -0
- data/.gitignore +16 -0
- data/.rubocop.yml +1156 -0
- data/.travis.yml +43 -0
- data/Configuration.md +149 -0
- data/Dockerfile +13 -0
- data/Gemfile +41 -0
- data/LICENSE +21 -0
- data/README.md +102 -0
- data/Rakefile +56 -0
- data/Tracing.md +145 -0
- data/Troubleshooting.md +32 -0
- data/benchmarks/Gemfile +7 -0
- data/benchmarks/id_generation.rb +12 -0
- data/benchmarks/opentracing.rb +26 -0
- data/benchmarks/rack_vanilla_vs_traced.rb +80 -0
- data/benchmarks/stackprof_rack_tracing.rb +77 -0
- data/benchmarks/time_processing.rb +12 -0
- data/bin/console +7 -0
- data/bin/setup +8 -0
- data/examples/opentracing.rb +31 -0
- data/examples/tracing.rb +80 -0
- data/gemfiles/libraries.gemfile +71 -0
- data/gemfiles/rails32.gemfile +51 -0
- data/gemfiles/rails42.gemfile +50 -0
- data/gemfiles/rails50.gemfile +52 -0
- data/instana.gemspec +46 -0
- data/lib/instana.rb +12 -0
- data/lib/instana/agent.rb +441 -0
- data/lib/instana/agent/helpers.rb +61 -0
- data/lib/instana/agent/hooks.rb +37 -0
- data/lib/instana/agent/tasks.rb +48 -0
- data/lib/instana/base.rb +54 -0
- data/lib/instana/collector.rb +116 -0
- data/lib/instana/collectors/gc.rb +57 -0
- data/lib/instana/collectors/memory.rb +34 -0
- data/lib/instana/collectors/thread.rb +30 -0
- data/lib/instana/config.rb +79 -0
- data/lib/instana/eum/eum-test.js.erb +16 -0
- data/lib/instana/eum/eum.js.erb +14 -0
- data/lib/instana/frameworks/cuba.rb +6 -0
- data/lib/instana/frameworks/instrumentation/abstract_mysql_adapter.rb +58 -0
- data/lib/instana/frameworks/instrumentation/action_controller.rb +183 -0
- data/lib/instana/frameworks/instrumentation/action_view.rb +43 -0
- data/lib/instana/frameworks/instrumentation/active_record.rb +27 -0
- data/lib/instana/frameworks/instrumentation/mysql2_adapter.rb +81 -0
- data/lib/instana/frameworks/instrumentation/mysql_adapter.rb +56 -0
- data/lib/instana/frameworks/instrumentation/postgresql_adapter.rb +71 -0
- data/lib/instana/frameworks/rails.rb +42 -0
- data/lib/instana/frameworks/roda.rb +6 -0
- data/lib/instana/frameworks/sinatra.rb +9 -0
- data/lib/instana/helpers.rb +40 -0
- data/lib/instana/instrumentation.rb +21 -0
- data/lib/instana/instrumentation/dalli.rb +78 -0
- data/lib/instana/instrumentation/excon.rb +74 -0
- data/lib/instana/instrumentation/grpc.rb +84 -0
- data/lib/instana/instrumentation/net-http.rb +66 -0
- data/lib/instana/instrumentation/rack.rb +77 -0
- data/lib/instana/instrumentation/redis.rb +82 -0
- data/lib/instana/instrumentation/resque.rb +131 -0
- data/lib/instana/instrumentation/rest-client.rb +34 -0
- data/lib/instana/instrumentation/sidekiq-client.rb +45 -0
- data/lib/instana/instrumentation/sidekiq-worker.rb +54 -0
- data/lib/instana/opentracing/carrier.rb +4 -0
- data/lib/instana/opentracing/tracer.rb +18 -0
- data/lib/instana/rack.rb +10 -0
- data/lib/instana/setup.rb +36 -0
- data/lib/instana/test.rb +40 -0
- data/lib/instana/thread_local.rb +15 -0
- data/lib/instana/tracer.rb +392 -0
- data/lib/instana/tracing/processor.rb +92 -0
- data/lib/instana/tracing/span.rb +401 -0
- data/lib/instana/tracing/span_context.rb +33 -0
- data/lib/instana/util.rb +261 -0
- data/lib/instana/version.rb +4 -0
- data/lib/oj_check.rb +16 -0
- data/lib/opentracing.rb +6 -0
- data/test/agent/agent_test.rb +143 -0
- data/test/apps/cuba.rb +15 -0
- data/test/apps/grpc_server.rb +81 -0
- data/test/apps/roda.rb +10 -0
- data/test/apps/sinatra.rb +5 -0
- data/test/benchmarks/bench_id_generation.rb +12 -0
- data/test/benchmarks/bench_opentracing.rb +13 -0
- data/test/config_test.rb +37 -0
- data/test/frameworks/cuba_test.rb +44 -0
- data/test/frameworks/rack_test.rb +167 -0
- data/test/frameworks/rails/actioncontroller_test.rb +93 -0
- data/test/frameworks/rails/actionview3_test.rb +255 -0
- data/test/frameworks/rails/actionview4_test.rb +254 -0
- data/test/frameworks/rails/actionview5_test.rb +221 -0
- data/test/frameworks/rails/activerecord3_test.rb +134 -0
- data/test/frameworks/rails/activerecord4_test.rb +134 -0
- data/test/frameworks/rails/activerecord5_test.rb +87 -0
- data/test/frameworks/roda_test.rb +44 -0
- data/test/frameworks/sinatra_test.rb +44 -0
- data/test/instana_test.rb +27 -0
- data/test/instrumentation/dalli_test.rb +253 -0
- data/test/instrumentation/excon_test.rb +147 -0
- data/test/instrumentation/grpc_test.rb +377 -0
- data/test/instrumentation/net-http_test.rb +160 -0
- data/test/instrumentation/redis_test.rb +119 -0
- data/test/instrumentation/resque_test.rb +128 -0
- data/test/instrumentation/rest-client_test.rb +55 -0
- data/test/instrumentation/sidekiq-client_test.rb +125 -0
- data/test/instrumentation/sidekiq-worker_test.rb +173 -0
- data/test/jobs/resque_error_job.rb +22 -0
- data/test/jobs/resque_fast_job.rb +20 -0
- data/test/jobs/sidekiq_job_1.rb +6 -0
- data/test/jobs/sidekiq_job_2.rb +7 -0
- data/test/models/block.rb +18 -0
- data/test/servers/grpc_50051.rb +20 -0
- data/test/servers/helpers/sidekiq_worker_initializer.rb +27 -0
- data/test/servers/rackapp_6511.rb +25 -0
- data/test/servers/rails_3205.rb +167 -0
- data/test/servers/sidekiq/worker.rb +27 -0
- data/test/test_helper.rb +145 -0
- data/test/tracing/custom_test.rb +158 -0
- data/test/tracing/id_management_test.rb +130 -0
- data/test/tracing/opentracing_test.rb +335 -0
- data/test/tracing/trace_test.rb +67 -0
- data/test/tracing/tracer_async_test.rb +198 -0
- data/test/tracing/tracer_test.rb +223 -0
- metadata +327 -0
data/.travis.yml
ADDED
@@ -0,0 +1,43 @@
|
|
1
|
+
language: ruby
|
2
|
+
|
3
|
+
cache:
|
4
|
+
bundler: true
|
5
|
+
directories:
|
6
|
+
- vendor/bundle
|
7
|
+
|
8
|
+
rvm:
|
9
|
+
- 2.5
|
10
|
+
- 2.4
|
11
|
+
|
12
|
+
before_install:
|
13
|
+
- gem update --system
|
14
|
+
- gem install bundler
|
15
|
+
- gem --version
|
16
|
+
|
17
|
+
before_script:
|
18
|
+
- psql -c 'create database travis_ci_test;' -U postgres
|
19
|
+
- mysql -e 'CREATE DATABASE travis_ci_test;'
|
20
|
+
|
21
|
+
script: "bundle exec rake test"
|
22
|
+
|
23
|
+
services:
|
24
|
+
- memcached
|
25
|
+
- redis
|
26
|
+
- mysql
|
27
|
+
- postgresql
|
28
|
+
|
29
|
+
gemfile:
|
30
|
+
- Gemfile
|
31
|
+
- gemfiles/libraries.gemfile
|
32
|
+
- gemfiles/rails50.gemfile
|
33
|
+
|
34
|
+
matrix:
|
35
|
+
exclude:
|
36
|
+
# Rails 5.0+ requires Ruby 2.2.2 or higher
|
37
|
+
- rvm: 2.1.10
|
38
|
+
gemfile: gemfiles/rails50.gemfile
|
39
|
+
|
40
|
+
notifications:
|
41
|
+
slack:
|
42
|
+
rooms:
|
43
|
+
secure: Ae9tJmBO9/sgYWthHRS5uufAf8s6uIMdtmQn+gBkcAXaMWJgt1IAzpIj98Qsg15/lhHS8ezwCe7WIAWC4mM1cnwl/hP195dbgLzF4D2uOjaIXj55ckIIE06jBX1yHapu0vMFSaKwgL4auEEVg4xkehBb9TzLNG/LbExadZQOIkeLdtgU04VrPfDC9pZWPplXT4kzjMZkMESzBYaCfNl6eenu0sHdoxSvngv52MImog6aZQKT+k3ccAa1yzZNhUdy4gSZi1HafXdSCn4UTPDtkNIlsWBW8yprICLxZV/NvgUTEEJYSHO6Ucx9Er22LzKtNbEYlAs1GErGWjDzpqvvXt/5UwNx0rLDrVKI/xMIELEbT047mSgJ8tpVd0ErGA/bnDfbF2oDFTAEXq4jaeAMaVR9Q1CW0ZZF2Jh5jOKc41U+AVGgaMDaBA0ukDSeXvJcnteZ9EllOO8ZAtC2FKtBNnj36W13KTR0TkjMCl+KOiVJXnOyRJIR+CUL9BdDuODBVPZHqZaZ48N+MOG9dRb+fvkdTnwh7hU+UmR08kOsd4x+dDlm4dBrFrB8v8udQ7XuBN9AOZty2CPWFUSJM1BxtetyS3We0L6lQ8o/B9STFNK4KTa/M8wNq1Fm85h3ZKHHIHDpQnXM6vD8SV1p9u91C5UI8rEyxzW5IaT2oqXsCzU=
|
data/Configuration.md
ADDED
@@ -0,0 +1,149 @@
|
|
1
|
+
# Configuration
|
2
|
+
|
3
|
+
## Global Enable/Disable
|
4
|
+
|
5
|
+
The entire gem can be disabled at runtime with:
|
6
|
+
|
7
|
+
```Ruby
|
8
|
+
::Instana.config[:enabled] = false # default: true
|
9
|
+
```
|
10
|
+
|
11
|
+
Other global enable/disable options are:
|
12
|
+
|
13
|
+
```Ruby
|
14
|
+
# Enable/Disable metrics collection and reporting
|
15
|
+
Instana.config[:metrics][:enabled] # default true
|
16
|
+
|
17
|
+
# Enable/Disable tracing
|
18
|
+
Instana.config[:tracing][:enabled] # default true
|
19
|
+
```
|
20
|
+
|
21
|
+
If you wish to disable the built-in instrumentation but still permit custom instrumentation, set the following environment variable for your application:
|
22
|
+
|
23
|
+
```sh
|
24
|
+
export INSTANA_DISABLE_AUTO_INSTR=true
|
25
|
+
```
|
26
|
+
|
27
|
+
## Agent Communication
|
28
|
+
|
29
|
+
The sensor tries to communicate with the Instana agent via IP 127.0.0.1 and as a fallback via the host's default gateway. Should the agent not be available under either of these IPs, e.g. due to iptables or other networking tricks, you can use the agentHost option to use a custom IP.
|
30
|
+
|
31
|
+
```Ruby
|
32
|
+
# Leverage environment variable
|
33
|
+
::Instana.config[:agent_host] = ENV['INSTANA_AGENT_HOST']
|
34
|
+
|
35
|
+
# Custom agent port
|
36
|
+
::Instana.config[:agent_port] = 42699
|
37
|
+
```
|
38
|
+
|
39
|
+
## Enabling/Disabling Individual Components
|
40
|
+
|
41
|
+
Individual components can be enabled and disabled with a local config.
|
42
|
+
|
43
|
+
To disable a single component in the gem, you can disable a single component with the following code:
|
44
|
+
|
45
|
+
```Ruby
|
46
|
+
::Instana.config[:metrics][:gc][:enabled] = false
|
47
|
+
```
|
48
|
+
Current metric components are `:gc`, `:memory` and `:thread`.
|
49
|
+
|
50
|
+
Instrumentation can be disabled as:
|
51
|
+
|
52
|
+
```Ruby
|
53
|
+
::Instana.config[:excon][:enabled] = false
|
54
|
+
::Instana.config[:rack][:enabled] = false
|
55
|
+
```
|
56
|
+
|
57
|
+
## Enable/Disable Backtrace Collection
|
58
|
+
|
59
|
+
Because backtraces are somewhat expensive in Ruby, backtrace collection is disabled by default but can be enabled with the following code:
|
60
|
+
|
61
|
+
```Ruby
|
62
|
+
::Instana.config[:collect_backtraces] = true
|
63
|
+
```
|
64
|
+
|
65
|
+
This will in-turn enable CodeView in your dashboard to get code level insights.
|
66
|
+
|
67
|
+
## Setting a Custom Service Name
|
68
|
+
|
69
|
+
You can set a custom service name for your application by setting the `INSTANA_SERVICE_NAME` environment variable:
|
70
|
+
|
71
|
+
```sh
|
72
|
+
export INSTANA_SERVICE_NAME=MrBlueSky
|
73
|
+
```
|
74
|
+
|
75
|
+
## Rack Middleware
|
76
|
+
|
77
|
+
This gem will detect and automagically insert the Instana Rack middleware into the middleware stack when a [supported framework](https://docs.instana.io/ecosystem/ruby/) is present. We are currently adding support for more frameworks. If you are using a yet to be instrumented framework, you can insert the Instana Rack middleware with the following:
|
78
|
+
|
79
|
+
```Ruby
|
80
|
+
require "instana/rack"
|
81
|
+
config.middleware.use ::Instana::Rack
|
82
|
+
```
|
83
|
+
|
84
|
+
...or whatever specific middleware call is appropriate for your framework.
|
85
|
+
|
86
|
+
|
87
|
+
## Managing the Agent Background Thread
|
88
|
+
|
89
|
+
This agent spawns a lightweight background thread to periodically collect and report metrics and traces. Be default, this uses a standard Ruby thread. If you wish to have greater control and potentially boot the agent reporting manually in an alternative thread system (such as actor based threads), you can do so with the following:
|
90
|
+
|
91
|
+
```Ruby
|
92
|
+
gem "instana", :require => "instana/setup"
|
93
|
+
```
|
94
|
+
|
95
|
+
...then in the background thread of your choice simply call:
|
96
|
+
|
97
|
+
```Ruby
|
98
|
+
::Instana.agent.start
|
99
|
+
```
|
100
|
+
|
101
|
+
Note that this call is blocking. It kicks off a loop of timers that periodically collects and reports metrics and trace data. This should only be called from inside an already initialized background thread:
|
102
|
+
|
103
|
+
```Ruby
|
104
|
+
Thread.new do
|
105
|
+
::Instana.agent.start
|
106
|
+
end
|
107
|
+
```
|
108
|
+
|
109
|
+
### Caveat
|
110
|
+
|
111
|
+
In the case of forking web servers such as Unicorn or Puma in clustered mode, the agent detects the pid change and re-spawns the background thread. If you are managing the background thread yourself with the steps above _and_ you are using a forking webserver (or anything else that may fork the original process), you should also do the following.
|
112
|
+
|
113
|
+
When a fork is detected, the agent handles the re-initialization and then calls `::Agent.instana.spawn_background_thread`. This by default uses the standard `Thread.new`. If you wish to control this, you should override this method by re-defining that method. For example:
|
114
|
+
|
115
|
+
```ruby
|
116
|
+
# This method can be overridden with the following:
|
117
|
+
#
|
118
|
+
module Instana
|
119
|
+
class Agent
|
120
|
+
def spawn_background_thread
|
121
|
+
# start/identify custom thread
|
122
|
+
::Instana.agent.start
|
123
|
+
end
|
124
|
+
end
|
125
|
+
end
|
126
|
+
```
|
127
|
+
|
128
|
+
## Logging
|
129
|
+
|
130
|
+
The Instana logger is a standard Ruby logger that logs debug, warn, info
|
131
|
+
(etc.) messages and can be set as follows:
|
132
|
+
|
133
|
+
```Ruby
|
134
|
+
require "logger"
|
135
|
+
::Instana.logger.level = ::Logger::WARN
|
136
|
+
```
|
137
|
+
|
138
|
+
The gem can be configured to use your application logger instead:
|
139
|
+
|
140
|
+
```
|
141
|
+
::Instana.logger = ::Rails.logger
|
142
|
+
```
|
143
|
+
|
144
|
+
### Debugging & More Verbosity
|
145
|
+
|
146
|
+
#### Environment Variable
|
147
|
+
|
148
|
+
Setting `INSTANA_DEBUG` to a non nil value will enable extra logging output generally useful
|
149
|
+
for development.
|
data/Dockerfile
ADDED
@@ -0,0 +1,13 @@
|
|
1
|
+
# For development/testing, you can run this instrumentation
|
2
|
+
# interactively in a Docker container:
|
3
|
+
# docker build -t instana/ruby-sensor-console:0.1
|
4
|
+
# docker run -it instana/ruby-sensor-console:0.1
|
5
|
+
#
|
6
|
+
FROM ruby:2.3.1
|
7
|
+
RUN apt-get update -qq && apt-get install -y build-essential libpq-dev nodejs openssh-client git vim zip curl uni2ascii bsdmainutils
|
8
|
+
RUN mkdir /ruby-sensor
|
9
|
+
WORKDIR /ruby-sensor
|
10
|
+
COPY Gemfile Gemfile.lock instana.gemspec ./
|
11
|
+
COPY . ./
|
12
|
+
RUN gem install bundler && bundle install --jobs 20 --retry 5
|
13
|
+
CMD bundle exec rake console
|
data/Gemfile
ADDED
@@ -0,0 +1,41 @@
|
|
1
|
+
source 'https://rubygems.org'
|
2
|
+
|
3
|
+
group :development, :test do
|
4
|
+
gem 'rake'
|
5
|
+
gem 'minitest', '5.9.1'
|
6
|
+
gem 'minitest-reporters'
|
7
|
+
gem 'minitest-debugger', :require => false
|
8
|
+
gem 'webmock'
|
9
|
+
gem 'puma'
|
10
|
+
|
11
|
+
# Rack v2 dropped support for Ruby 2.2 and higher.
|
12
|
+
if RUBY_VERSION < '2.2'
|
13
|
+
gem 'rack', '~> 1.6'
|
14
|
+
end
|
15
|
+
gem 'rack-test'
|
16
|
+
|
17
|
+
# public_suffix dropped support for Ruby 2.1 and earlier.
|
18
|
+
gem 'public_suffix', '< 3.0'
|
19
|
+
end
|
20
|
+
|
21
|
+
group :development do
|
22
|
+
gem 'ruby-debug', :platforms => [:mri_18, :jruby]
|
23
|
+
gem 'debugger', :platform => :mri_19
|
24
|
+
gem 'stackprof', :platform => [:mri_19, :mri_20]
|
25
|
+
|
26
|
+
if RUBY_VERSION > '1.8.7'
|
27
|
+
gem 'pry'
|
28
|
+
|
29
|
+
if RUBY_VERSION < '2.2'
|
30
|
+
gem 'byebug', '< 9.1.0', :platform => [:mri_19, :mri_20]
|
31
|
+
gem 'pry-byebug', :platform => [:mri_19, :mri_20]
|
32
|
+
else
|
33
|
+
gem 'pry-byebug', :platform => [:mri_19, :mri_20]
|
34
|
+
end
|
35
|
+
else
|
36
|
+
gem 'pry', '0.9.12.4'
|
37
|
+
end
|
38
|
+
end
|
39
|
+
|
40
|
+
# instana.gemspec
|
41
|
+
gemspec
|
data/LICENSE
ADDED
@@ -0,0 +1,21 @@
|
|
1
|
+
MIT License
|
2
|
+
|
3
|
+
Copyright (c) 2017 Instana
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
13
|
+
copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
21
|
+
SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,102 @@
|
|
1
|
+
<div align="center">
|
2
|
+
<img src="http://www.instana.com/wp-content/uploads/2016/11/Instana-Infrastructure-Map-1-1024x551.png"/>
|
3
|
+
</div>
|
4
|
+
|
5
|
+
# Instana
|
6
|
+
|
7
|
+
The Instana gem provides Ruby metrics and traces (request, queue & cross-host) for [Instana](https://www.instana.com/).
|
8
|
+
|
9
|
+
[![Build Status](https://travis-ci.org/instana/ruby-sensor.svg?branch=master)](https://travis-ci.org/instana/ruby-sensor)
|
10
|
+
[![Code
|
11
|
+
Climate](https://codeclimate.com/github/instana/ruby-sensor/badges/gpa.svg)](https://codeclimate.com/github/instana/ruby-sensor)
|
12
|
+
[![Gem Version](https://badge.fury.io/rb/instana.svg)](https://badge.fury.io/rb/instana)
|
13
|
+
[![OpenTracing Badge](https://img.shields.io/badge/OpenTracing-enabled-blue.svg)](http://opentracing.io)
|
14
|
+
|
15
|
+
## Note
|
16
|
+
|
17
|
+
This gem supports Ruby versions 2.0 or greater.
|
18
|
+
|
19
|
+
Any and all feedback is welcome. Happy Ruby visibility.
|
20
|
+
|
21
|
+
[![rails](https://s3.amazonaws.com/instana/rails-logo.jpg?1)](http://rubyonrails.org/)
|
22
|
+
[![roda](https://s3.amazonaws.com/instana/roda-logo.png?1)](http://roda.jeremyevans.net/)
|
23
|
+
[![cuba](https://s3.amazonaws.com/instana/cuba-logo.png?1)](http://cuba.is/)
|
24
|
+
[![mina logo 100px](https://cloud.githubusercontent.com/assets/395132/23832558/fcd5bdb2-0736-11e7-9809-3016e89698e2.png)](https://github.com/instana/mina-instana)
|
25
|
+
[![sinatra](https://s3.amazonaws.com/instana/sinatra-logo.png?1)](http://www.sinatrarb.com/)
|
26
|
+
[![padrino](https://s3.amazonaws.com/instana/padrino-logo.png?1)](http://padrinorb.com/)
|
27
|
+
[![rack](https://s3.amazonaws.com/instana/rack-logo.png?1)](https://rack.github.io/)
|
28
|
+
[![rack](https://user-images.githubusercontent.com/395132/27842764-27e0e452-610d-11e7-811f-8575f83b8944.png?1)](http://www.grpc.io/)
|
29
|
+
|
30
|
+
## Installation
|
31
|
+
|
32
|
+
The gem is available on [Rubygems](https://rubygems.org/gems/instana). To install, add this line to _the end_ of your application's Gemfile:
|
33
|
+
|
34
|
+
```ruby
|
35
|
+
gem 'instana'
|
36
|
+
```
|
37
|
+
|
38
|
+
And then execute:
|
39
|
+
|
40
|
+
$ bundle
|
41
|
+
|
42
|
+
Or install it yourself as:
|
43
|
+
|
44
|
+
$ gem install instana
|
45
|
+
|
46
|
+
## Usage
|
47
|
+
|
48
|
+
The instana gem is a zero configuration tool that will automatically collect key metrics from your Ruby processes. Just install and go.
|
49
|
+
|
50
|
+
## Configuration
|
51
|
+
|
52
|
+
Although the gem has no configuration required for out of the box metrics and tracing, components can be configured if needed. See [Configuration.md](https://github.com/instana/ruby-sensor/blob/master/Configuration.md).
|
53
|
+
|
54
|
+
## Tracing
|
55
|
+
|
56
|
+
This Ruby gem provides a simple API for tracing and also supports [OpenTracing](http://opentracing.io/). See [Tracing.md](https://github.com/instana/ruby-sensor/blob/master/Tracing.md) for details.
|
57
|
+
|
58
|
+
## Documentation
|
59
|
+
|
60
|
+
You can find more documentation covering supported components and minimum versions in the Instana [documentation portal](https://docs.instana.io/ecosystem/ruby/).
|
61
|
+
|
62
|
+
## Want End User Monitoring?
|
63
|
+
|
64
|
+
Instana provides deep end user monitoring that links server side traces with browser events.
|
65
|
+
|
66
|
+
For Ruby templates and views, get your EUM API key from your Instana dashboard and you can call `::Instana::Helpers.eum_snippet('example_api_key_string')` from within your layout file. This will output
|
67
|
+
a small javascript snippet of code to instrument browser events. It's based on [Weasel](https://github.com/instana/weasel). Check it out.
|
68
|
+
|
69
|
+
As an example for Haml, you could do the following:
|
70
|
+
|
71
|
+
```ruby
|
72
|
+
%html{ :lang => "en", :xmlns => "http://www.w3.org/1999/xhtml" }
|
73
|
+
%head
|
74
|
+
- if user_signed_in?
|
75
|
+
= raw ::Instana::Helpers.eum_snippet('example_api_key_string', :username => current_user.username)
|
76
|
+
- else
|
77
|
+
= raw ::Instana::Helpers.eum_snippet('example_api_key_string')
|
78
|
+
%body
|
79
|
+
```
|
80
|
+
Make sure to use the `raw` helper so the javascript isn't interpolated with escape strings.
|
81
|
+
|
82
|
+
The optional second argument to `::Instana::Helpers.eum_snippet` is a hash of metadata key/values that will be reported along
|
83
|
+
with the browser instrumentation.
|
84
|
+
|
85
|
+
![Instana EUM example with metadata](https://s3.amazonaws.com/instana/Instana+Gameface+EUM+with+metadata+2016-12-22+at+15.32.01.png)
|
86
|
+
|
87
|
+
See also the [End User Monitoring](https://docs.instana.io/products/website_monitoring/) in the Instana documentation portal.
|
88
|
+
|
89
|
+
## Development
|
90
|
+
|
91
|
+
After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
|
92
|
+
|
93
|
+
To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
|
94
|
+
|
95
|
+
## Contributing
|
96
|
+
|
97
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/instana/ruby-sensor.
|
98
|
+
|
99
|
+
## More
|
100
|
+
|
101
|
+
Want to instrument other languages? See our [Nodejs instrumentation](https://github.com/instana/nodejs-sensor), [Go instrumentation](https://github.com/instana/golang-sensor) or [many other supported technologies](https://www.instana.com/supported-technologies/).
|
102
|
+
|
data/Rakefile
ADDED
@@ -0,0 +1,56 @@
|
|
1
|
+
require "bundler/gem_tasks"
|
2
|
+
require "rake/testtask"
|
3
|
+
|
4
|
+
Rake::TestTask.new(:test) do |t|
|
5
|
+
t.verbose = false
|
6
|
+
t.warning = false
|
7
|
+
t.ruby_opts = []
|
8
|
+
|
9
|
+
t.libs << "test"
|
10
|
+
t.libs << "lib"
|
11
|
+
t.test_files = FileList['test/**/*_test.rb']
|
12
|
+
|
13
|
+
if ENV.key?('BUNDLE_GEMFILE')
|
14
|
+
case File.basename(ENV['BUNDLE_GEMFILE']).split('.').first
|
15
|
+
when /rails50/
|
16
|
+
t.test_files = %w(test/frameworks/rails/activerecord5_test.rb
|
17
|
+
test/frameworks/rails/actioncontroller_test.rb
|
18
|
+
test/frameworks/rails/actionview5_test.rb)
|
19
|
+
when /rails42/
|
20
|
+
t.test_files = %w(test/frameworks/rails/activerecord4_test.rb
|
21
|
+
test/frameworks/rails/actioncontroller_test.rb
|
22
|
+
test/frameworks/rails/actionview4_test.rb)
|
23
|
+
when /rails32/
|
24
|
+
t.test_files = %w(test/frameworks/rails/activerecord3_test.rb
|
25
|
+
test/frameworks/rails/actioncontroller_test.rb
|
26
|
+
test/frameworks/rails/actionview3_test.rb)
|
27
|
+
when /libraries/
|
28
|
+
t.test_files = FileList['test/instrumentation/*_test.rb',
|
29
|
+
'test/frameworks/cuba_test.rb',
|
30
|
+
'test/frameworks/roda_test.rb',
|
31
|
+
'test/frameworks/sinatra_test.rb']
|
32
|
+
else
|
33
|
+
t.test_files = FileList['test/agent/*_test.rb'] +
|
34
|
+
FileList['test/tracing/*_test.rb'] +
|
35
|
+
FileList['test/profiling/*_test.rb'] +
|
36
|
+
FileList['test/benchmarks/bench_*.rb']
|
37
|
+
end
|
38
|
+
else
|
39
|
+
t.test_files = FileList['test/agent/*_test.rb'] +
|
40
|
+
FileList['test/tracing/*_test.rb'] +
|
41
|
+
FileList['test/profiling/*_test.rb'] +
|
42
|
+
FileList['test/benchmarks/bench_*.rb']
|
43
|
+
end
|
44
|
+
end
|
45
|
+
|
46
|
+
task :environment do
|
47
|
+
ENV['INSTANA_DEBUG'] = 'true'
|
48
|
+
Bundler.require(:default, :development)
|
49
|
+
end
|
50
|
+
|
51
|
+
task :console => :environment do
|
52
|
+
ARGV.clear
|
53
|
+
Pry.start
|
54
|
+
end
|
55
|
+
|
56
|
+
task :default => :spec
|
data/Tracing.md
ADDED
@@ -0,0 +1,145 @@
|
|
1
|
+
# Tracing
|
2
|
+
|
3
|
+
Tracing with Instana is automatic but if you want even more visibility into custom code or some in-house
|
4
|
+
component, you can use Instana's tracing API or [OpenTracing](http://opentracing.io/).
|
5
|
+
|
6
|
+
# OpenTracing
|
7
|
+
|
8
|
+
Existing applications that utilize the OpenTracing API or those who wish to add support should have no problem
|
9
|
+
as the Instana Ruby gem fully supports the OpenTracing specification.
|
10
|
+
|
11
|
+
To start, simply set the Instana tracer as the global tracer for OpenTracing:
|
12
|
+
|
13
|
+
```Ruby
|
14
|
+
require 'opentracing'
|
15
|
+
OpenTracing.global_tracer = ::Instana.tracer
|
16
|
+
```
|
17
|
+
|
18
|
+
Then OpenTracing code can be run normally:
|
19
|
+
|
20
|
+
```Ruby
|
21
|
+
begin
|
22
|
+
span = OpenTracing.start_span('job')
|
23
|
+
# The code to be instrumented
|
24
|
+
@id = User.find_by_name('john.smith')
|
25
|
+
span.set_tag(:job_id, @id)
|
26
|
+
rescue => e
|
27
|
+
span.set_tag(:error, e.message)
|
28
|
+
ensure
|
29
|
+
span.finish
|
30
|
+
end
|
31
|
+
```
|
32
|
+
|
33
|
+
# The Instana Ruby API
|
34
|
+
|
35
|
+
The Instana Ruby gem provides a simple to use API to trace any arbitrary part of your application.
|
36
|
+
|
37
|
+
To instrument a section of code, it can be simply done with:
|
38
|
+
|
39
|
+
```Ruby
|
40
|
+
begin
|
41
|
+
::Instana.tracer.log_entry(:mywork, { :helpful_kvs => @user.id })
|
42
|
+
# The code to be instrumented
|
43
|
+
@id = User.find_by_name('john.smith')
|
44
|
+
rescue => e
|
45
|
+
::Instana.tracer.log_error(e)
|
46
|
+
ensure
|
47
|
+
::Instana.tracer.log_exit(:mywork, { :found_id => @id })
|
48
|
+
end
|
49
|
+
```
|
50
|
+
|
51
|
+
or alternatively you can use the `trace` block method that will automagically capture and
|
52
|
+
log any exceptions raised:
|
53
|
+
|
54
|
+
```Ruby
|
55
|
+
::Instana.tracer.trace(:mywork, { :helpful_kvs => @user.id }) do
|
56
|
+
# The code to be instrumented
|
57
|
+
@id = User.find_by_name('john.smith')
|
58
|
+
end
|
59
|
+
```
|
60
|
+
|
61
|
+
The above are simple examples but shows how easy it is to instrument any arbitrary piece of code you like.
|
62
|
+
|
63
|
+
See the [examples directory](https://github.com/instana/ruby-sensor/blob/master/examples/tracing.rb) for
|
64
|
+
an expanded view and quick cheat sheet on tracing.
|
65
|
+
|
66
|
+
# Asynchronous Tracing
|
67
|
+
|
68
|
+
Some operations that you want to trace might be asynchronous meaning that they may return immediately
|
69
|
+
but will still continue to work out of band. To do this, you can use the `log_async_*` related
|
70
|
+
tracing methods:
|
71
|
+
|
72
|
+
```Ruby
|
73
|
+
::Instana.tracer.log_entry(:prep_job, { :helpful_kvs => @job.name })
|
74
|
+
|
75
|
+
http_ops = {:get => "/", :post => "/post_data"}
|
76
|
+
|
77
|
+
cb_block = Proc.new do |response, payload|
|
78
|
+
# The callback block that is invoked on HTTP response (payload == t_context)
|
79
|
+
#
|
80
|
+
# process response
|
81
|
+
#
|
82
|
+
::Instana.tracer.log_async_exit(:http_op, :status => response.status, payload)
|
83
|
+
end
|
84
|
+
|
85
|
+
http_ops.each do |op|
|
86
|
+
t_context = ::Instana.tracer.log_async_entry(:http_op)
|
87
|
+
|
88
|
+
# Example op that returns immediately
|
89
|
+
request_id = connection.async_request(op, cb_block, t_context)
|
90
|
+
|
91
|
+
::Instana.tracer.log_async_info({:request_id => request_id}, t_context)
|
92
|
+
end
|
93
|
+
```
|
94
|
+
|
95
|
+
# Carrying Context into New Threads
|
96
|
+
|
97
|
+
Tracing is thread local. If you spawn a new thread the context must be carried to that new thread and then picked up.
|
98
|
+
|
99
|
+
```Ruby
|
100
|
+
# Get the tracing context
|
101
|
+
t_context = ::Instana.tracer.context
|
102
|
+
|
103
|
+
# Spawn new thread
|
104
|
+
Thread.new do
|
105
|
+
# Pickup context in this thread with `t_context`
|
106
|
+
::Instana.tracer.log_start_or_continue(:async_thread, { :async_start => 1 }, t_context)
|
107
|
+
|
108
|
+
# Continue tracing work as usual
|
109
|
+
begin
|
110
|
+
::Instana.tracer.log_entry(:mywork, { :helpful_kvs => @user.id })
|
111
|
+
# The code to be instrumented
|
112
|
+
@id = User.find_by_name('john.smith')
|
113
|
+
rescue => e
|
114
|
+
::Instana.tracer.log_error(e)
|
115
|
+
ensure
|
116
|
+
::Instana.tracer.log_exit(:mywork, { :found_id => @id })
|
117
|
+
end
|
118
|
+
end
|
119
|
+
```
|
120
|
+
# Tracing Jobs Scheduled for Later
|
121
|
+
|
122
|
+
Jobs that are queued to be run later can be instrumented as such:
|
123
|
+
|
124
|
+
```Ruby
|
125
|
+
::Instana.tracer.log_entry(:prep_job, { :job_name => @job.name })
|
126
|
+
|
127
|
+
# Get the current tracing context
|
128
|
+
t_context = ::Instana.tracer.context
|
129
|
+
|
130
|
+
# The Async proc (job) that will be executed out of band.
|
131
|
+
block = Proc.new do
|
132
|
+
# This will pickup context and link the two traces (root + job)
|
133
|
+
t_context = ::Instana.tracer.log_start_or_continue_trace(:my_async_op, { :helpful_kvs => true }, t_context)
|
134
|
+
#
|
135
|
+
# Some Asynchronous work to be done
|
136
|
+
#
|
137
|
+
::Instana.tracer.log_info({:job_name => Job.get(id).name})
|
138
|
+
# More Asynchronous work
|
139
|
+
::Instana.tracer.log_end(:my_async_op, { :job_success => true })
|
140
|
+
end
|
141
|
+
|
142
|
+
MyClass.run_in_5_minutes(block)
|
143
|
+
|
144
|
+
::Instana.tracer.log_exit(:prep_job, { :prep_successful => true })
|
145
|
+
```
|