opencensus 0.2.2 → 0.3.0

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
  SHA1:
3
- metadata.gz: 5b61331cb69913aa2a85bed2353045cf10b97d99
4
- data.tar.gz: 6fed28a666fa2741fd7de32a3608c0089b8f7b8c
3
+ metadata.gz: 42681c2940ade96a318ba521ab0c6d28064a5084
4
+ data.tar.gz: 06b1d23140c3bb582ba11b0d05c918585c4d073e
5
5
  SHA512:
6
- metadata.gz: 1afcf27bef5d796b2b08f31bebaccd78ed03ff93e463c24ecaae4a4ff98dd20cc6ccbf9c953cbbfe477018a2ae4091589fdca4584c78a17154961592d0a41e0f
7
- data.tar.gz: 4daea1fabb7dff90fbccbb9e043489c6c9f9a5c16714058d9cb87783d025aa5a8adaef175aed3953127ae0a6c653078a8c9c95bd8439c5b9ce75b3d11d42fc07
6
+ metadata.gz: 132b2e15377b4a6eddb3ca5688fde6dc709bad8189175acd0fb3226840c7bdd5ca01014fc520b18212c808ece97fd21a88860884fbdb016245d841d8f897d413
7
+ data.tar.gz: 3bed182ab9c3d94f8043e7ce98bcde78da6ce7fefdef8356b320845dffdf0383e2ad5b090e148261244dbc95e188f96c3740df67129432b51f7a24dce480307a
data/.gitignore CHANGED
@@ -11,3 +11,5 @@
11
11
  /docs/_site
12
12
  /docs/Gemfile.lock
13
13
  /docs/api/
14
+
15
+ /examples/*/Gemfile.lock
data/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  # Release History
2
2
 
3
+ ### 0.3.0 / 2018-03-26
4
+
5
+ * SpanContext#build_contained_spans honors sampling bit.
6
+ * Use AlwaysSample as the default sampler.
7
+ * Support the Span.kind field.
8
+
3
9
  ### 0.2.2 / 2018-03-09
4
10
 
5
11
  * Railtie now adds the middleware at the end of the stack by default, and provides a config that can customize the position
data/README.md CHANGED
@@ -77,10 +77,11 @@ into the request so you can potentially connect your request trace with that of
77
77
  the remote service. Here is an example:
78
78
 
79
79
  ```ruby
80
+ require "opencensus/trace/integrations/rack_middleware"
80
81
  conn = Faraday.new(url: "http://www.example.com") do |c|
81
82
  c.use OpenCensus::Trace::Integrations::FaradayMiddleware
82
83
  c.adapter Faraday.default_adapter
83
- end
84
+ end
84
85
  conn.get "/"
85
86
  ```
86
87
 
@@ -0,0 +1,5 @@
1
+ source "https://rubygems.org"
2
+
3
+ gem "faraday", "~> 0.14"
4
+ gem "opencensus", "~> 0.3"
5
+ gem "sinatra", "~> 2.0"
@@ -0,0 +1,33 @@
1
+ # Hello World example
2
+
3
+ This example application demonstrates how to use OpenCensus to record traces for a Sinatra-based web application.
4
+
5
+ ## Prerequisites
6
+
7
+ Ruby 2.2 or later is required. Make sure you have Bundler installed as well.
8
+
9
+ gem install bundler
10
+
11
+ ## Installation
12
+
13
+ Get the example from the OpenCensus Ruby repository on Github, and cd into the example application directory.
14
+
15
+ git clone https://github.com/census-instrumentation/opencensus-ruby.git
16
+ cd opencensus-ruby/examples/hello-world
17
+
18
+ Install the dependencies using Bundler.
19
+
20
+ bundle install
21
+
22
+ ## Running the example
23
+
24
+ Run the application locally on your workstation with:
25
+
26
+ bundle exec ruby hello.rb
27
+
28
+ This will run on port 4567 by default, and display application logs on the terminal. From a separate shell, you can send requests using a tool such as curl:
29
+
30
+ curl http://localhost:4567/
31
+ curl http://localhost:4567/lengthy
32
+
33
+ The running application will log the captured traces.
@@ -0,0 +1,59 @@
1
+ # Copyright 2018 OpenCensus Authors
2
+ #
3
+ # Licensed under the Apache License, Version 2.0 (the "License");
4
+ # you may not use this file except in compliance with the License.
5
+ # You may obtain a copy of the License at
6
+ #
7
+ # http://www.apache.org/licenses/LICENSE-2.0
8
+ #
9
+ # Unless required by applicable law or agreed to in writing, software
10
+ # distributed under the License is distributed on an "AS IS" BASIS,
11
+ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12
+ # See the License for the specific language governing permissions and
13
+ # limitations under the License.
14
+
15
+
16
+ # This is a simple Sinatra application demonstrating how to record traces
17
+ # using OpenCensus.
18
+ #
19
+ # It uses the OpenCensus Rack middleware to trace all incoming requests. It
20
+ # also demonstrates how to use the Faraday middleware to trace outgoing HTTP
21
+ # requests, as well as how to instrument your code to capture custom spans.
22
+ #
23
+ # By default, the resulting trace data is logged in JSON format. You can also
24
+ # configure OpenCensus to report traces to a backend such as Stackdriver or
25
+ # Zipkin using an exporter plugin library.
26
+
27
+ require "sinatra"
28
+
29
+ # Install the Rack middleware to trace incoming requests.
30
+ require "opencensus/trace/integrations/rack_middleware"
31
+ use OpenCensus::Trace::Integrations::RackMiddleware
32
+
33
+ # Access the Faraday middleware which will be used to trace outgoing HTTP
34
+ # requests.
35
+ require "opencensus/trace/integrations/faraday_middleware"
36
+
37
+ # Each request will be traced automatically by the middleware.
38
+ get "/" do
39
+ "Hello world!"
40
+ end
41
+
42
+ # Traces for this request will also include sub-spans as indicated below.
43
+ get "/lengthy" do
44
+ # Configure this Faraday connection with a middleware to trace outgoing
45
+ # requests.
46
+ conn = Faraday.new(url: "http://www.google.com") do |c|
47
+ c.use OpenCensus::Trace::Integrations::FaradayMiddleware
48
+ c.adapter Faraday.default_adapter
49
+ end
50
+ conn.get "/"
51
+
52
+ # You may instrument your code to create custom spans for long-running
53
+ # operations.
54
+ OpenCensus::Trace.in_span "long task" do
55
+ sleep rand
56
+ end
57
+
58
+ "Done!"
59
+ end
@@ -124,16 +124,18 @@ module OpenCensus
124
124
  # Will throw an exception if there is no current SpanContext.
125
125
  #
126
126
  # @param [String] name Name of the span
127
+ # @param [Symbol] kind Kind of span. Defaults to unspecified.
127
128
  # @param [Sampler] sampler Span-scoped sampler. If not provided,
128
129
  # defaults to the trace configuration's default sampler.
129
130
  #
130
131
  # @return [SpanBuilder] A SpanBuilder object that you can use to
131
132
  # set span attributes and create children.
132
133
  #
133
- def start_span name, skip_frames: 0, sampler: nil
134
+ def start_span name, kind: nil, skip_frames: 0, sampler: nil
134
135
  context = span_context
135
136
  raise "No currently active span context" unless context
136
- span = context.start_span name, skip_frames: skip_frames + 1,
137
+ span = context.start_span name, kind: kind,
138
+ skip_frames: skip_frames + 1,
137
139
  sampler: sampler
138
140
  self.span_context = span.context
139
141
  span
@@ -151,11 +153,13 @@ module OpenCensus
151
153
  # will create subspans.
152
154
  #
153
155
  # @param [String] name Name of the span
156
+ # @param [Symbol] kind Kind of span. Defaults to unspecified.
154
157
  # @param [Sampler] sampler Span-scoped sampler. If not provided,
155
158
  # defaults to the trace configuration's default sampler.
156
159
  #
157
- def in_span name, skip_frames: 0, sampler: nil
158
- span = start_span name, skip_frames: skip_frames + 1, sampler: sampler
160
+ def in_span name, kind: nil, skip_frames: 0, sampler: nil
161
+ span = start_span name, kind: kind, skip_frames: skip_frames + 1,
162
+ sampler: sampler
159
163
  begin
160
164
  yield span
161
165
  ensure
@@ -20,8 +20,7 @@ module OpenCensus
20
20
  module Trace
21
21
  # Schema of the Trace configuration. See Trace#configure for more info.
22
22
  @config = Common::Config.new do |config|
23
- default_sampler =
24
- Samplers::Probability.new Samplers::Probability::DEFAULT_RATE
23
+ default_sampler = Samplers::AlwaysSample.new
25
24
  config.add_option! :default_sampler, default_sampler do |value|
26
25
  value.respond_to? :call
27
26
  end
@@ -54,6 +54,7 @@ module OpenCensus
54
54
  def format_span span
55
55
  {
56
56
  name: format_value(span.name),
57
+ kind: span.kind,
57
58
  trace_id: span.trace_id,
58
59
  span_id: span.span_id,
59
60
  parent_span_id: span.parent_span_id,
@@ -145,6 +145,7 @@ module OpenCensus
145
145
  # @private Set span attributes from request object
146
146
  #
147
147
  def start_request span, env
148
+ span.kind = SpanBuilder::CLIENT
148
149
  req_method = env[:method]
149
150
  span.put_attribute "/http/method", req_method if req_method
150
151
  url = env[:url]
@@ -111,6 +111,7 @@ module OpenCensus
111
111
  end
112
112
 
113
113
  def start_request span, env
114
+ span.kind = SpanBuilder::SERVER
114
115
  span.put_attribute "/http/host", get_host(env)
115
116
  span.put_attribute "/http/url", get_url(env)
116
117
  span.put_attribute "/http/method", env["REQUEST_METHOD"]
@@ -20,6 +20,21 @@ module OpenCensus
20
20
  # or have a parent span, and may have zero or more children.
21
21
  #
22
22
  class Span
23
+ ## The span kind is unspecified
24
+ SPAN_KIND_UNSPECIFIED = :SPAN_KIND_UNSPECIFIED
25
+
26
+ ##
27
+ # Indicates that the span covers server-side handling of an RPC or other
28
+ # remote network request.
29
+ #
30
+ SERVER = :SERVER
31
+
32
+ ##
33
+ # Indicates that the span covers the client-side wrapper around an RPC
34
+ # or other remote request.
35
+ #
36
+ CLIENT = :CLIENT
37
+
23
38
  ##
24
39
  # A unique identifier for a trace. All spans from the same trace share
25
40
  # the same `trace_id`. The ID is a 16-byte value represented as a
@@ -54,6 +69,15 @@ module OpenCensus
54
69
  #
55
70
  attr_reader :name
56
71
 
72
+ ##
73
+ # The kind of span. Can be used to specify additional relationships
74
+ # between spans in addition to a parent/child relationship.
75
+ # You should use the kind constants provided by this class.
76
+ #
77
+ # @return [Symbol]
78
+ #
79
+ attr_reader :kind
80
+
57
81
  ##
58
82
  # The starting timestamp of this span in UTC.
59
83
  #
@@ -177,6 +201,7 @@ module OpenCensus
177
201
  # @private
178
202
  #
179
203
  def initialize trace_id, span_id, name, start_time, end_time,
204
+ kind: SPAN_KIND_UNSPECIFIED,
180
205
  parent_span_id: "", attributes: {},
181
206
  dropped_attributes_count: 0, stack_trace: [],
182
207
  dropped_frames_count: 0, time_events: [],
@@ -186,6 +211,7 @@ module OpenCensus
186
211
  same_process_as_parent_span: nil,
187
212
  child_span_count: nil
188
213
  @name = name
214
+ @kind = kind
189
215
  @trace_id = trace_id
190
216
  @span_id = span_id
191
217
  @parent_span_id = parent_span_id
@@ -194,9 +220,8 @@ module OpenCensus
194
220
  @attributes = attributes
195
221
  @dropped_attributes_count = dropped_attributes_count
196
222
  @stack_trace = stack_trace
197
- @stack_trace_hash_id = [stack_trace, dropped_frames_count].hash
198
- @stack_trace_hash_id = -1 if @stack_trace_hash_id.zero?
199
223
  @dropped_frames_count = dropped_frames_count
224
+ @stack_trace_hash_id = init_stack_trace_hash_id
200
225
  @time_events = time_events
201
226
  @dropped_annotations_count = dropped_annotations_count
202
227
  @dropped_message_events_count = dropped_message_events_count
@@ -206,6 +231,13 @@ module OpenCensus
206
231
  @same_process_as_parent_span = same_process_as_parent_span
207
232
  @child_span_count = child_span_count
208
233
  end
234
+
235
+ private
236
+
237
+ def init_stack_trace_hash_id
238
+ hash_id = [@stack_trace, @dropped_frames_count].hash
239
+ hash_id.zero? ? -1 : hash_id
240
+ end
209
241
  end
210
242
  end
211
243
  end
@@ -33,6 +33,21 @@ module OpenCensus
33
33
  ## The linked span is a parent of the current span.
34
34
  PARENT_LINKED_SPAN = :PARENT_LINKED_SPAN
35
35
 
36
+ ## The span kind is unspecified
37
+ SPAN_KIND_UNSPECIFIED = :SPAN_KIND_UNSPECIFIED
38
+
39
+ ##
40
+ # Indicates that the span covers server-side handling of an RPC or other
41
+ # remote network request.
42
+ #
43
+ SERVER = :SERVER
44
+
45
+ ##
46
+ # Indicates that the span covers the client-side wrapper around an RPC
47
+ # or other remote request.
48
+ #
49
+ CLIENT = :CLIENT
50
+
36
51
  ##
37
52
  # The context that can build children of this span.
38
53
  #
@@ -90,6 +105,18 @@ module OpenCensus
90
105
  #
91
106
  attr_accessor :name
92
107
 
108
+ ##
109
+ # The kind of span. Can be used to specify additional relationships
110
+ # between spans in addition to a parent/child relationship.
111
+ # Valid values are `SpanBuilder::CLIENT`, `SpanBuilder::SERVER`, and
112
+ # `SpanBuilder::SPAN_KIND_UNSPECIFIED`.
113
+ #
114
+ # This field is required.
115
+ #
116
+ # @return [Symbol]
117
+ #
118
+ attr_accessor :kind
119
+
93
120
  ##
94
121
  # The start time of the span. On the client side, this is the time kept
95
122
  # by the local machine where the span execution starts. On the server
@@ -330,6 +357,7 @@ module OpenCensus
330
357
  same_process_as_parent_span = context.parent.same_process_as_parent
331
358
 
332
359
  Span.new trace_id, span_id, built_name, @start_time, @end_time,
360
+ kind: @kind,
333
361
  parent_span_id: parent_span_id,
334
362
  attributes: built_attributes,
335
363
  dropped_attributes_count: dropped_attributes_count,
@@ -357,6 +385,7 @@ module OpenCensus
357
385
  @context = span_context
358
386
  @sampled = sampled
359
387
  @name = ""
388
+ @kind = SPAN_KIND_UNSPECIFIED
360
389
  @start_time = nil
361
390
  @end_time = nil
362
391
  @attributes = {}
@@ -167,19 +167,21 @@ module OpenCensus
167
167
  # However, you are responsible for finishing the span yourself.
168
168
  #
169
169
  # @param [String] name Name of the span
170
+ # @param [Symbol] kind Kind of span. Defaults to unspecified.
170
171
  # @param [Sampler] sampler Span-scoped sampler. If not provided,
171
172
  # defaults to the trace configuration's default sampler.
172
173
  #
173
174
  # @return [SpanBuilder] A SpanBuilder object that you can use to
174
175
  # set span attributes and create children.
175
176
  #
176
- def start_span name, skip_frames: 0, sampler: nil
177
+ def start_span name, kind: nil, skip_frames: 0, sampler: nil
177
178
  child_context = create_child
178
179
  sampler ||= OpenCensus::Trace.config.default_sampler
179
180
  sampled = sampler.call span_context: self
180
181
  span = SpanBuilder.new child_context, sampled,
181
182
  skip_frames: skip_frames + 1
182
183
  span.name = name
184
+ span.kind = kind if kind
183
185
  span.start!
184
186
  @trace_data.span_map[child_context.span_id] = span
185
187
  end
@@ -194,11 +196,13 @@ module OpenCensus
194
196
  # be finished automatically at the end of the block.
195
197
  #
196
198
  # @param [String] name Name of the span
199
+ # @param [Symbol] kind Kind of span. Defaults to unspecified.
197
200
  # @param [Sampler] sampler Span-scoped sampler. If not provided,
198
201
  # defaults to the trace configuration's default sampler.
199
202
  #
200
- def in_span name, skip_frames: 0, sampler: nil
201
- span = start_span name, skip_frames: skip_frames + 1, sampler: sampler
203
+ def in_span name, kind: nil, skip_frames: 0, sampler: nil
204
+ span = start_span name, kind: kind, skip_frames: skip_frames + 1,
205
+ sampler: sampler
202
206
  begin
203
207
  yield span
204
208
  ensure
@@ -232,9 +236,9 @@ module OpenCensus
232
236
  end
233
237
 
234
238
  ##
235
- # Builds all finished spans under this context, and returns an array of
236
- # built `Span` objects. Ignores any unfinished spans. The order of the
237
- # generated spans is undefined.
239
+ # Builds spans under this context, and returns an array of built `Span`
240
+ # objects. Builds only spans that are both finished and sampled, and
241
+ # ignores others. The order of the generated spans is undefined.
238
242
  #
239
243
  # Does not build any ancestor spans. If you want the entire span tree
240
244
  # built, call this method on the `#root` context.
@@ -260,7 +264,10 @@ module OpenCensus
260
264
  max_message_events: nil,
261
265
  max_links: nil,
262
266
  max_string_length: nil
263
- contained_span_builders.find_all(&:finished?).map do |sb|
267
+ sampled_span_builders = contained_span_builders.find_all do |sb|
268
+ sb.finished? && sb.sampled
269
+ end
270
+ sampled_span_builders.map do |sb|
264
271
  sb.to_span max_attributes: max_attributes,
265
272
  max_stack_frames: max_stack_frames,
266
273
  max_annotations: max_annotations,
@@ -14,5 +14,5 @@
14
14
 
15
15
  module OpenCensus
16
16
  ## Current OpenCensus version
17
- VERSION = "0.2.2".freeze
17
+ VERSION = "0.3.0".freeze
18
18
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: opencensus
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.2
4
+ version: 0.3.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Jeff Ching
@@ -9,7 +9,7 @@ authors:
9
9
  autorequire:
10
10
  bindir: exe
11
11
  cert_chain: []
12
- date: 2018-03-09 00:00:00.000000000 Z
12
+ date: 2018-03-26 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: bundler
@@ -164,6 +164,9 @@ files:
164
164
  - docs/_config.yml
165
165
  - docs/_layouts/default.html
166
166
  - docs/index.md
167
+ - examples/hello-world/Gemfile
168
+ - examples/hello-world/README.md
169
+ - examples/hello-world/hello.rb
167
170
  - lib/opencensus.rb
168
171
  - lib/opencensus/common.rb
169
172
  - lib/opencensus/common/config.rb