instana 1.10.6-java → 1.10.7-java

This diff has not been reviewed by any users.
Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 352414e953a17f64e0919b5a2c27dbda21e620daaf3c72c30280cfb2098a4f6a
4
- data.tar.gz: 90da54dcb420ef55b29bb4199b32092ee17ce3885fed1960d4a5c22d14807158
3
+ metadata.gz: c9ae0af0a3e6a372b7fe53e21eb34613994be152ec5941fe9192e238fc83ca92
4
+ data.tar.gz: 405cea0367043d3389a7de25c0637801fb6376a42f45d043b22852982ae66809
5
5
  SHA512:
6
- metadata.gz: 05d209853ffe6030b399b2a21146c769015b3ffa8623155f25934748f57d064ed0cd2592e6d1185786730a086c0eb2fe6dd7dcf257eabbdc5649b93dd68e6a14
7
- data.tar.gz: f09dd0bfcdaaf8cb988d08c5453aae99f14e426355108ed7cb0c73b913245a16aed9663c7f367f19632b395c08f9ef7dda25bb34bfe9a477e48e90e3a919d903
6
+ metadata.gz: 9e699fb09a39844e295787394efe28479d9d1979540a91072bb8e747fd1c424303e15ce3eeec001cf69cfc39ded6d6a488683cf0605be253219309f8fc8435c7
7
+ data.tar.gz: a59016b9739d46366c1960f49b4fb197e2e593a34af898ddf82fc088c47fa3d780fd4ccdd80992fda8b78565245ca9690d03cf36c4b5ded187abf520b5f3e110
data/README.md CHANGED
@@ -45,15 +45,15 @@ Or install it yourself as:
45
45
 
46
46
  ## Usage
47
47
 
48
- The instana gem is a zero configuration tool that will automatically collect key metrics from your Ruby processes. Just install and go.
48
+ The instana gem is a zero configuration tool that will automatically collect key metrics and distributed traces from your Ruby processes. Just install and go.
49
49
 
50
50
  ## Configuration
51
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).
52
+ Although the gem has no configuration required for out of the box metrics and tracing, components can be configured if needed. See our [Configuration](https://docs.instana.io/ecosystem/ruby/configuration/) page.
53
53
 
54
54
  ## Tracing
55
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.
56
+ This Ruby gem provides a simple API for tracing and also supports [OpenTracing](http://opentracing.io/). See the [Ruby Tracing SDK](https://docs.instana.io/ecosystem/ruby/tracing-sdk/) and [OpenTracing](https://docs.instana.io/ecosystem/ruby/opentracing/) pages for details.
57
57
 
58
58
  ## Documentation
59
59
 
@@ -67,9 +67,9 @@ See the [End User Monitoring](/products/website_monitoring/#configuration) page
67
67
 
68
68
  ## Development
69
69
 
70
- 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.
70
+ After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bundle exec rake console` for an interactive prompt that will allow you to experiment.
71
71
 
72
- 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).
72
+ To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `lib/instana/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).
73
73
 
74
74
  ## Contributing
75
75
 
@@ -77,5 +77,5 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/instan
77
77
 
78
78
  ## More
79
79
 
80
- 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/).
80
+ Want to instrument other languages? See our [Node.js](https://github.com/instana/nodejs-sensor), [Go](https://github.com/instana/golang-sensor), [Python](https://github.com/instana/python-sensor) repositories or [many other supported technologies](https://www.instana.com/supported-technologies/).
81
81
 
@@ -119,11 +119,15 @@ module Instana
119
119
  # - :announced
120
120
  # - :ready
121
121
  def setup
122
+ if ENV.key?('INSTANA_DISABLE')
123
+ ::Instana.logger.info "Instana gem disabled via environment variable (INSTANA_DISABLE). Going to sit in a corner..."
124
+ end
125
+
122
126
  # The announce timer
123
127
  # We attempt to announce this ruby sensor to the host agent.
124
128
  # In case of failure, we try again in 30 seconds.
125
129
  @announce_timer = @timers.now_and_every(30) do
126
- if @state == :unannounced
130
+ if @state == :unannounced && !ENV.key?('INSTANA_DISABLE')
127
131
  if host_agent_available? && announce_sensor
128
132
  transition_to(:announced)
129
133
  ::Instana.logger.debug "Announce successful. Waiting on ready. (#{@state} pid:#{Process.pid} #{@process[:name]})"
@@ -176,7 +180,7 @@ module Instana
176
180
  # called from an already initialized background thread.
177
181
  #
178
182
  def start
179
- if !host_agent_available?
183
+ if !ENV.key?('INSTANA_DISABLE') && !host_agent_available?
180
184
  if !ENV.key?("INSTANA_QUIET")
181
185
  ::Instana.logger.info "Instana host agent not available. Will retry periodically. (Set env INSTANA_QUIET=1 to shut these messages off)"
182
186
  end
@@ -16,9 +16,8 @@ module Instana
16
16
  @config[:agent_port] = 42699
17
17
  end
18
18
 
19
- # Global on/off switch for prebuilt environments
20
- # Setting this to false will disable this gem
21
- # from doing anything.
19
+ # This option has been DEPRECATED. Use the INSTANA_DISABLE environment variable instead.
20
+ # https://docs.instana.io/ecosystem/ruby/configuration/
22
21
  @config[:enabled] = true
23
22
 
24
23
  # Enable/disable metrics globally or individually (default: all enabled)
@@ -7,6 +7,8 @@ module Instana
7
7
 
8
8
  # Returns a processed javascript snippet to be placed within the HEAD tag of an HTML page.
9
9
  #
10
+ # DEPRECATED: This method will be removed in a future version.
11
+ #
10
12
  def eum_snippet(api_key, kvs = {})
11
13
  return nil if !::Instana.tracer.tracing?
12
14
 
@@ -23,6 +25,8 @@ module Instana
23
25
  # Returns a processed javascript snippet to be placed within the HEAD tag of an HTML page.
24
26
  # This one is used for testing only
25
27
  #
28
+ # DEPRECATED: This method will be removed in a future version.
29
+ #
26
30
  def eum_test_snippet(api_key, kvs = {})
27
31
  return nil if !::Instana.tracer.tracing?
28
32
 
@@ -2,8 +2,12 @@ module Instana
2
2
  AUTOLOAD_DIRECTORIES = [:instrumentation, :frameworks].freeze
3
3
  end
4
4
 
5
-
6
- if !ENV.key?('INSTANA_DISABLE_AUTO_INSTR') || ENV['INSTANA_DISABLE_AUTO_INSTR'] === 'false'
5
+ # Environment variables:
6
+ #
7
+ # INSTANA_DISABLE_AUTO_INSTR, unless set to false, will disable loading of automatic instrumentation
8
+ # INSTANA_DISABLE disables the gem entirely and therefore doesn't load automatic instrumentation
9
+ #
10
+ if (!ENV.key?('INSTANA_DISABLE_AUTO_INSTR') || ENV['INSTANA_DISABLE_AUTO_INSTR'] === 'false') && !ENV.key?('INSTANA_DISABLE')
7
11
  #
8
12
  # Load all of the files in the specified subdirectories
9
13
  #
@@ -1,4 +1,4 @@
1
1
  module Instana
2
- VERSION = "1.10.6"
2
+ VERSION = "1.10.7"
3
3
  VERSION_FULL = "instana-#{VERSION}"
4
4
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: instana
3
3
  version: !ruby/object:Gem::Version
4
- version: 1.10.6
4
+ version: 1.10.7
5
5
  platform: java
6
6
  authors:
7
7
  - Peter Giacomo Lombardo
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2019-09-20 00:00:00.000000000 Z
11
+ date: 2019-09-23 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  requirement: !ruby/object:Gem::Requirement
@@ -135,14 +135,11 @@ files:
135
135
  - ".gitignore"
136
136
  - ".rubocop.yml"
137
137
  - ".travis.yml"
138
- - Configuration.md
139
138
  - Dockerfile
140
139
  - Gemfile
141
140
  - LICENSE
142
141
  - README.md
143
142
  - Rakefile
144
- - Tracing.md
145
- - Troubleshooting.md
146
143
  - benchmarks/10k-rack-traces.rb
147
144
  - benchmarks/Gemfile
148
145
  - benchmarks/Gemfile.lock
@@ -1,149 +0,0 @@
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/Tracing.md DELETED
@@ -1,145 +0,0 @@
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
- ```
@@ -1,32 +0,0 @@
1
- # Troubleshooting
2
-
3
- The Instana gem has been designed to be fully automatic in process metric reporting and trace reporting. But if something
4
- goes wrong, you can use the following steps and tips to potentially diagnose any issues that may exist.
5
-
6
- # Supported Components
7
-
8
- Make sure that the component that you want to get visibility into has been added to the support matrix. A list of all
9
- supported components can be found in the [documentation](https://docs.instana.io/ecosystem/ruby/).
10
-
11
- # Logging & Environment Variables
12
-
13
- By default, the gem will log informational messages on boot that will indicate if any problems were encountered. If you
14
- set the `INSTANA_DEBUG` environment variable, it will increase the amount of logging output.
15
-
16
- ![instana console output](https://s3.amazonaws.com/instana/Instana+Ruby+boot+console+logging+output.png)
17
-
18
- In the example above, you can see that the host agent isn't available. Once the host agent is available, the Instana
19
- gem will automatically re-connect without any intervention.
20
-
21
- There are even more methods to control logging output. See the [Configuration](https://github.com/instana/ruby-sensor/blob/master/Configuration.md#logging)
22
- document for details.
23
-
24
- # Testing in your Application
25
-
26
- To diagnose the Instana gem from your application, often simply opening an application console with verbose logging can be
27
- enough to identify any potential issues:
28
-
29
- ![rails console](https://s3.amazonaws.com/instana/Instana+Ruby+Rails+console+output.png)
30
-
31
- In the example above, you can see the Instana Ruby gem initialize, instrument some components and a success notification: `Host agent available. We're
32
- in business`.