opencensus 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 47862e6aad5e10aa18a54f75679e2886c753127d
-  data.tar.gz: a534f715d68bb80323efe18ff61eab3776f6365c
+  metadata.gz: 90ff804d909c01ac8eb0ba83fd0add78451b186f
+  data.tar.gz: 16805cbe660a480f7aa52a3e3cb25ff8a799f039
 SHA512:
-  metadata.gz: 67d7652f2ffd69c7338b975ef1b9200054dda31bd9bc64283ef4038ac1afb46b57780cd97ffaa6bd1dfc2403de84842c7b83e3020cfdfcdfee1b3083dd480513
-  data.tar.gz: bad91bedd06219d6669a1982b25853d7a9fffb4a2de2ef4fc5c3297c1937a6d72e8eec1928f68d12e94d9df689dcb6ca8d11622585d0720861e46070f7f5fe35
+  metadata.gz: 6be6ad106a73d7f5972e5eba7af5449a484bc04e6c967ffd3d59d4776bb4c9d2d79308938fe0d7bc538f4d95b0fc567c286a9d21056a9695e52ac5c049016597
+  data.tar.gz: 9557b149c2ba5997152d511c22149b2c21922e6ec723d7fa0ecf0571f83440afd086e2a6a1c8c4e55bbd5f22989f4bbc434ccd298525d9a428c70b6739e79954

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Release History
+
+### 0.2.0 / 2018-02-13
+
+* Span creation sets the "same_process_as_parent_span" field if possible.
+* The "stack_trace_hash_id" field was missing from the interfaces. Fixed.
+* Nullability of a few fields did not match the proto specs. Fixed.
+* Fixed some documentation errors and omissions.
+
+### 0.1.0 / 2018-01-12
+
+Initial release of the core library, including:
+
+* Trace interfaces
+* Rack integration
+* Rails integration
+* Faraday integration
+* Logging exporter

data/README.md

@@ -130,7 +130,7 @@ config.opencensus.trace.default_sampler =
 config.opencensus.trace.default_max_attributes = 16
 ```
 
-You can configure a variety of core OpenCensuys options, including:
+You can configure a variety of core OpenCensus options, including:
 
 * Sampling, which controls how often a request is traced.
 * Exporting, which controls how trace information is reported.

data/Rakefile

@@ -17,4 +17,8 @@ YARD::Rake::YardocTask.new do |t|
  t.stats_options = ['--list-undoc']         # optional
 end
 
+task :faster do
+  ENV["FASTER_TESTS"] = "true"
+end
+
 task :default => [:test, :rubocop, :yard]

data/lib/opencensus/trace.rb

@@ -88,9 +88,14 @@ module OpenCensus
       #
       # @param [TraceContextData] trace_context The request's incoming trace
       #      context (optional)
-      #
-      def start_request_trace trace_context: nil
-        span_context = SpanContext.create_root trace_context: trace_context
+      # @param [boolean, nil] same_process_as_parent Set to `true` if the parent
+      #      span is local, `false` if it is remote, or `nil` if there is no
+      #      parent span or this information is not available.
+      #
+      def start_request_trace trace_context: nil, same_process_as_parent: nil
+        span_context = SpanContext.create_root \
+          trace_context: trace_context,
+          same_process_as_parent: same_process_as_parent
         self.span_context = span_context
         if block_given?
           begin

data/lib/opencensus/trace/exporters/logger.rb

@@ -48,6 +48,9 @@ module OpenCensus
 
         private
 
+        # rubocop:disable Metrics/MethodLength
+        # rubocop:disable Metrics/AbcSize
+
         def format_span span
           {
             name: format_value(span.name),
@@ -60,6 +63,7 @@ module OpenCensus
             dropped_attributes_count: span.dropped_attributes_count,
             stack_trace: span.stack_trace,
             dropped_frames_count: span.dropped_frames_count,
+            stack_trace_hash_id: span.stack_trace_hash_id,
             time_events: span.time_events.map { |te| format_time_event(te) },
             dropped_annotations_count: span.dropped_annotations_count,
             dropped_message_events_count: span.dropped_message_events_count,
@@ -71,6 +75,9 @@ module OpenCensus
           }
         end
 
+        # rubocop:enable Metrics/MethodLength
+        # rubocop:enable Metrics/AbcSize
+
         def format_time_event time_event
           case time_event
           when Annotation

data/lib/opencensus/trace/integrations/rack_middleware.rb

@@ -70,7 +70,9 @@ module OpenCensus
             context = formatter.deserialize env[formatter.rack_header_name]
           end
 
-          Trace.start_request_trace trace_context: context do |span_context|
+          Trace.start_request_trace \
+            trace_context: context,
+            same_process_as_parent: false do |span_context|
             begin
               span_context.in_span get_path(env) do |span|
                 start_request span, env

data/lib/opencensus/trace/message_event.rb

@@ -58,7 +58,7 @@ module OpenCensus
       # The number of compressed bytes sent or received. If zero, assumed to
       # be the same size as uncompressed.
       #
-      # @return [Integer, nil]
+      # @return [Integer]
       #
       attr_reader :compressed_size
 
@@ -67,7 +67,7 @@ module OpenCensus
       #
       # @private
       #
-      def initialize type, id, uncompressed_size, compressed_size: nil,
+      def initialize type, id, uncompressed_size, compressed_size: 0,
                      time: nil
         super time: time
         @type = type

data/lib/opencensus/trace/span.rb

@@ -79,6 +79,9 @@ module OpenCensus
       # The number of attributes that were discarded. Attributes can be
       # discarded because their keys are too long or because there are too
       # many attributes. If this value is 0, then no attributes were dropped.
+      #
+      # @return [Integer]
+      #
       attr_reader :dropped_attributes_count
 
       ##
@@ -88,6 +91,15 @@ module OpenCensus
       #
       attr_reader :stack_trace
 
+      ##
+      # A hash of the stack trace. This may be used by exporters to identify
+      # duplicate stack traces transmitted in the same request; only one copy
+      # of the actual data needs to be sent.
+      #
+      # @return [Integer]
+      #
+      attr_reader :stack_trace_hash_id
+
       ##
       # The number of stack frames that were dropped because there were too many
       # stack frames. If this value is 0, then no stack frames were dropped.
@@ -138,6 +150,7 @@ module OpenCensus
       # An optional final status for this span.
       #
       # @return [Status, nil]
+      #
       attr_reader :status
 
       ##
@@ -145,7 +158,7 @@ module OpenCensus
       # crosses a process boundary. True when the parent_span belongs to the
       # same process as the current span.
       #
-      # @return [Boolean]
+      # @return [boolean, nil]
       #
       attr_reader :same_process_as_parent_span
 
@@ -170,7 +183,7 @@ module OpenCensus
                      dropped_annotations_count: 0,
                      dropped_message_events_count: 0, links: [],
                      dropped_links_count: 0, status: nil,
-                     same_process_as_parent_span: true,
+                     same_process_as_parent_span: nil,
                      child_span_count: nil
         @name = name
         @trace_id = trace_id
@@ -181,6 +194,8 @@ module OpenCensus
         @attributes = attributes
         @dropped_attributes_count = dropped_attributes_count
         @stack_trace = stack_trace
+        @stack_trace_hash_id = [stack_trace, dropped_frames_count].hash
+        @stack_trace_hash_id = -1 if @stack_trace_hash_id.zero?
         @dropped_frames_count = dropped_frames_count
         @time_events = time_events
         @dropped_annotations_count = dropped_annotations_count

data/lib/opencensus/trace/span_builder.rb

@@ -279,6 +279,21 @@ module OpenCensus
       ##
       # Return a read-only version of this span
       #
+      # @param [Integer, nil] max_attributes The maximum number of attributes
+      #     to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_stack_frames The maximum number of stack
+      #     frames to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_annotations The maximum number of annotations
+      #     to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_message_events The maximum number of message
+      #     events to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_links The maximum number of links to save,
+      #     or `nil` to use the config value.
+      # @param [Integer, nil] max_string_length The maximum length in bytes for
+      #     truncated strings, or `nil` to use the config value.
+      # @param [Integer, nil] child_span_count The number of child spans to
+      #     declare, or `nil` to omit the `child_span_count` field.
+      #
       # @return [Span]
       #
       def to_span max_attributes: nil,
@@ -287,7 +302,7 @@ module OpenCensus
                   max_message_events: nil,
                   max_links: nil,
                   max_string_length: nil,
-                  same_process_as_parent_span: nil
+                  child_span_count: nil
 
         raise "Span must have start_time" unless @start_time
         raise "Span must have end_time" unless @end_time
@@ -312,6 +327,7 @@ module OpenCensus
         built_links = builder.convert_links @links
         dropped_links_count = @links.size - built_links.size
         built_status = builder.convert_status @status_code, @status_message
+        same_process_as_parent_span = context.parent.same_process_as_parent
 
         Span.new trace_id, span_id, built_name, @start_time, @end_time,
                  parent_span_id: parent_span_id,
@@ -325,7 +341,8 @@ module OpenCensus
                  links: built_links,
                  dropped_links_count: dropped_links_count,
                  status: built_status,
-                 same_process_as_parent_span: same_process_as_parent_span
+                 same_process_as_parent_span: same_process_as_parent_span,
+                 child_span_count: child_span_count
       end
 
       # rubocop:enable Metrics/MethodLength

data/lib/opencensus/trace/span_context.rb

@@ -15,9 +15,9 @@
 module OpenCensus
   module Trace
     ##
-    # Span represents a span in a trace record. Spans are contained in
-    # a trace and arranged in a forest. That is, each span may be a root span
-    # or have a parent span, and may have zero or more children.
+    # SpanContext represents the context within which a span may be created.
+    # It includes the ID of the parent trace, the ID of the parent span, and
+    # sampling state.
     #
     class SpanContext
       ##
@@ -51,19 +51,23 @@ module OpenCensus
         #
         # @param [TraceContextData] trace_context The request's incoming trace
         #      context (optional)
+        # @param [boolean, nil] same_process_as_parent Set to `true` if the
+        #      parent span is local, `false` if it is remote, or `nil` if there
+        #      is no parent span or this information is not available.
         #
         # @return [SpanContext]
         #
-        def create_root trace_context: nil
+        def create_root trace_context: nil, same_process_as_parent: nil
           if trace_context
             trace_data = TraceData.new \
               trace_context.trace_id, trace_context.trace_options, {}
-            new trace_data, nil, trace_context.span_id
+            new trace_data, nil, trace_context.span_id,
+                same_process_as_parent
           else
             trace_id = rand 1..MAX_TRACE_ID
             trace_id = trace_id.to_s(16).rjust(32, "0")
             trace_data = TraceData.new trace_id, 0, {}
-            new trace_data, nil, ""
+            new trace_data, nil, "", nil
           end
         end
       end
@@ -132,6 +136,14 @@ module OpenCensus
       #
       attr_reader :span_id
 
+      ##
+      # Whether the parent of spans created by this context is local, or `nil`
+      # if this context creates root spans or this information is unknown.
+      #
+      # @return [boolean, nil]
+      #
+      attr_reader :same_process_as_parent
+
       ##
       # Whether the context (e.g. the parent span) has been sampled. This
       # information may be used in sampling decisions for new spans.
@@ -227,10 +239,35 @@ module OpenCensus
       # Does not build any ancestor spans. If you want the entire span tree
       # built, call this method on the `#root` context.
       #
+      # @param [Integer, nil] max_attributes The maximum number of attributes
+      #     to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_stack_frames The maximum number of stack
+      #     frames to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_annotations The maximum number of annotations
+      #     to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_message_events The maximum number of message
+      #     events to save, or `nil` to use the config value.
+      # @param [Integer, nil] max_links The maximum number of links to save,
+      #     or `nil` to use the config value.
+      # @param [Integer, nil] max_string_length The maximum length in bytes for
+      #     truncated strings, or `nil` to use the config value.
+      #
       # @return [Array<Span>] Built Span objects
       #
-      def build_contained_spans
-        contained_span_builders.find_all(&:finished?).map(&:to_span)
+      def build_contained_spans max_attributes: nil,
+                                max_stack_frames: nil,
+                                max_annotations: nil,
+                                max_message_events: nil,
+                                max_links: nil,
+                                max_string_length: nil
+        contained_span_builders.find_all(&:finished?).map do |sb|
+          sb.to_span max_attributes: max_attributes,
+                     max_stack_frames: max_stack_frames,
+                     max_annotations: max_annotations,
+                     max_message_events: max_message_events,
+                     max_links: max_links,
+                     max_string_length: max_string_length
+        end
       end
 
       ##
@@ -240,10 +277,11 @@ module OpenCensus
       #
       # @private
       #
-      def initialize trace_data, parent, span_id
+      def initialize trace_data, parent, span_id, same_process_as_parent
         @trace_data = trace_data
         @parent = parent
         @span_id = span_id
+        @same_process_as_parent = same_process_as_parent
       end
 
       ##
@@ -289,7 +327,7 @@ module OpenCensus
           child_span_id = rand 1..MAX_SPAN_ID
           child_span_id = child_span_id.to_s(16).rjust(16, "0")
           unless @trace_data.span_map.key? child_span_id
-            return SpanContext.new @trace_data, self, child_span_id
+            return SpanContext.new @trace_data, self, child_span_id, true
           end
         end
       end

data/lib/opencensus/version.rb

@@ -14,5 +14,5 @@
 
 module OpenCensus
   ## Current OpenCensus version
-  VERSION = "0.1.0".freeze
+  VERSION = "0.2.0".freeze
 end

data/opencensus.gemspec

@@ -6,8 +6,8 @@ require "opencensus/version"
 Gem::Specification.new do |spec|
   spec.name          = "opencensus"
   spec.version       = OpenCensus::VERSION
-  spec.authors       = ["Jeff Ching"]
-  spec.email         = ["chingor@google.com"]
+  spec.authors       = ["Jeff Ching", "Daniel Azuma"]
+  spec.email         = ["chingor@google.com", "dazuma@google.com"]
 
   spec.summary       = %q{A stats collection and distributed tracing framework}
   spec.description   = %q{A stats collection and distributed tracing framework}

metadata

@@ -1,14 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: opencensus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Jeff Ching
+- Daniel Azuma
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-12 00:00:00.000000000 Z
+date: 2018-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -125,6 +126,7 @@ dependencies:
 description: A stats collection and distributed tracing framework
 email:
 - chingor@google.com
+- dazuma@google.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -133,6 +135,7 @@ files:
 - ".rubocop.yml"
 - ".travis.yml"
 - AUTHORS
+- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - Gemfile