opencensus 0.1.0

data/lib/opencensus/trace/link.rb

@@ -0,0 +1,90 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module OpenCensus
+  module Trace
+    ##
+    # A pointer from the current span to another span in the same trace or in
+    # a different trace. For example, this can be used in batching operations,
+    # where a single batch handler processes multiple requests from different
+    # traces or when the handler receives a request from a different project.
+    #
+    class Link
+      # The relationship of the two spans is unknown, or known but other
+      # than parent-child.
+      TYPE_UNSPECIFIED    = :TYPE_UNSPECIFIED
+
+      # The linked span is a child of the current span.
+      CHILD_LINKED_SPAN   = :CHILD_LINKED_SPAN
+
+      # The linked span is a parent of the current span.
+      PARENT_LINKED_SPAN  = :PARENT_LINKED_SPAN
+
+      ##
+      # A unique identifier for a trace. All spans from the same trace share
+      # the same `trace_id`. The ID is a 16-byte represented as a hexadecimal
+      # string.
+      #
+      # @return [String]
+      #
+      attr_reader :trace_id
+
+      ##
+      # A unique identifier for a span within a trace, assigned when the span
+      # is created. The ID is a 16-byte represented as a hexadecimal string.
+      #
+      # @return [String]
+      #
+      attr_reader :span_id
+
+      ##
+      # The relationship of the current span relative to the linked span. You
+      # should use the type constants provided by this class.
+      #
+      # @return [Symbol]
+      #
+      attr_reader :type
+
+      ##
+      # A set of attributes on the link.
+      #
+      # @return [Hash<String, (TruncatableString, Integer, Boolean)>]
+      #
+      attr_reader :attributes
+
+      ##
+      # 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
+
+      ##
+      # Create a Link object.
+      #
+      # @private
+      #
+      def initialize trace_id, span_id, type: nil,
+                     attributes: {}, dropped_attributes_count: 0
+        @trace_id = trace_id
+        @span_id = span_id
+        @type = type
+        @attributes = attributes
+        @dropped_attributes_count = dropped_attributes_count
+      end
+    end
+  end
+end

data/lib/opencensus/trace/message_event.rb

@@ -0,0 +1,80 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "opencensus/trace/time_event"
+
+module OpenCensus
+  module Trace
+    ##
+    # An event describing a message sent/received between Spans.
+    #
+    class MessageEvent < TimeEvent
+      # Unknown event type.
+      TYPE_UNSPECIFIED = :TYPE_UNSPECIFIED
+
+      # Indicates a sent message.
+      SENT = :SENT
+
+      # Indicates a received message.
+      RECEIVED = :RECEIVED
+
+      ##
+      # The type of MessageEvent. Indicates whether the message was sent or
+      # received. You should use the type constants provided by this class.
+      #
+      # @return [Symbol]
+      #
+      attr_reader :type
+
+      ##
+      # An identifier for the MessageEvent's message that can be used to match
+      # SENT and RECEIVED MessageEvents. For example, this field could
+      # represent a sequence ID for a streaming RPC. It is recommended to be
+      # unique within a Span.
+      #
+      # @return [Integer]
+      #
+      attr_reader :id
+
+      ##
+      # The number of uncompressed bytes sent or received.
+      #
+      # @return [Integer]
+      #
+      attr_reader :uncompressed_size
+
+      ##
+      # The number of compressed bytes sent or received. If zero, assumed to
+      # be the same size as uncompressed.
+      #
+      # @return [Integer, nil]
+      #
+      attr_reader :compressed_size
+
+      ##
+      # Create a new MessageEvent object.
+      #
+      # @private
+      #
+      def initialize type, id, uncompressed_size, compressed_size: nil,
+                     time: nil
+        super time: time
+        @type = type
+        @id = id
+        @uncompressed_size = uncompressed_size
+        @compressed_size = compressed_size
+      end
+    end
+  end
+end

data/lib/opencensus/trace/samplers.rb

@@ -0,0 +1,50 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "opencensus/trace/samplers/always_sample"
+require "opencensus/trace/samplers/never_sample"
+require "opencensus/trace/samplers/probability"
+require "opencensus/trace/samplers/max_qps"
+
+module OpenCensus
+  module Trace
+    ##
+    # A sampler determines whether a given request's latency trace should
+    # actually be reported. It is usually not necessary to trace every
+    # request, especially for an application serving heavy traffic. You may
+    # use a sampler to decide, for a given request, whether to report its
+    # trace.
+    #
+    # The OpenCensus specification defines three samplers: AlwaysSample,
+    # NeverSample, and Probability. The Ruby implementation also provides a
+    # fourth, MaxQPS, based on the Stackdriver library.
+    #
+    # A sampler is a Proc that takes a hash of environment information and
+    # returns a boolean indicating whether or not to sample the current
+    # request. Alternately, it could be an object that duck-types the Proc
+    # interface by implementing the `call` method. The hash passed to `call`
+    # may contain the following keys, all of which are optional. Samplers must
+    # adjust their behavior to account for the availability or absence of any
+    # environment information:
+    #
+    # *   `span_context` The SpanContext that created the span being sampled.
+    # *   `rack_env` The hash of Rack environment information
+    #
+    # Applications may set a default sampler in the config. In addition, the
+    # sampler may be overridden whenever a span is created.
+    #
+    module Samplers
+    end
+  end
+end

data/lib/opencensus/trace/samplers/always_sample.rb

@@ -0,0 +1,34 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module OpenCensus
+  module Trace
+    module Samplers
+      ##
+      # The AlwaysSample sampler always returns true.
+      #
+      class AlwaysSample
+        ##
+        # Implements the sampler contract. Checks to see whether a sample
+        # should be taken at this time.
+        #
+        # @return [boolean] Whether to sample at this time.
+        #
+        def call _opts = {}
+          true
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/samplers/max_qps.rb

@@ -0,0 +1,55 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module OpenCensus
+  module Trace
+    module Samplers
+      ##
+      # The MaxQPS sampler delays a minimum amount of time between each sample,
+      # enforcing a maximum QPS across traces that use this sampler.
+      #
+      class MaxQPS
+        ##
+        # Create a sampler for the given QPS.
+        #
+        # @param [Number] qps Samples per second. Default is 0.1.
+        #
+        def initialize qps = 0.1
+          @delay_secs = 1.0 / qps
+          @last_time = ::Time.now.to_f - @delay_secs
+        end
+
+        ##
+        # Implements the sampler contract. Checks to see whether a sample
+        # should be taken at this time.
+        #
+        # @return [boolean] Whether to sample at this time.
+        #
+        def call _opts = {}
+          time = ::Time.now.to_f
+          delays = (time - @last_time) / @delay_secs
+          if delays >= 2.0
+            @last_time = time - @delay_secs
+            true
+          elsif delays >= 1.0
+            @last_time += @delay_secs
+            true
+          else
+            false
+          end
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/samplers/never_sample.rb

@@ -0,0 +1,34 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module OpenCensus
+  module Trace
+    module Samplers
+      ##
+      # The NeverSample sampler always returns false.
+      #
+      class NeverSample
+        ##
+        # Implements the sampler contract. Checks to see whether a sample
+        # should be taken at this time.
+        #
+        # @return [boolean] Whether to sample at this time.
+        #
+        def call _opts = {}
+          false
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/samplers/probability.rb

@@ -0,0 +1,69 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module OpenCensus
+  module Trace
+    module Samplers
+      ##
+      # The Probability sampler uses a random number generator against a
+      # configured rate to determine whether or not to sample.
+      #
+      class Probability
+        ##
+        # The default sampling probability.
+        #
+        DEFAULT_RATE = 0.1
+
+        ##
+        # Create a sampler for the given probability.
+        #
+        # @param [Number] rate Probability that we will sample. This value must
+        #        be between 0 and 1.
+        # @param [#rand] rng The random number generator to use. Default is a
+        #        new Random instance.
+        #
+        def initialize rate, rng: nil
+          if rate > 1 || rate < 0
+            raise ArgumentError, "Invalid rate - must be between 0 and 1."
+          end
+          @rate = rate
+          @rng = rng || Random.new
+        end
+
+        ##
+        # Implements the sampler contract. Checks to see whether a sample
+        # should be taken at this time.
+        #
+        # @param [Hash] opts The options to sample with.
+        # @option opts [SpanContext] :span_context If provided, the span context
+        #         will be used to generate a deterministic value in place of the
+        #         pseudo-random number generator.        #
+        # @return [boolean] Whether to sample at this time.
+        #
+        def call opts = {}
+          span_context = opts[:span_context]
+          return true if span_context && span_context.sampled?
+          value =
+            if span_context
+              (span_context.trace_id.to_i(16) % 0x10000000000000000).to_f /
+                0x10000000000000000
+            else
+              @rng.rand
+            end
+          value <= @rate
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/trace/span.rb

@@ -0,0 +1,196 @@
+# Copyright 2017 OpenCensus Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+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.
+    #
+    class Span
+      ##
+      # A unique identifier for a trace. All spans from the same trace share
+      # the same `trace_id`. The ID is a 16-byte value represented as a
+      # hexadecimal string.
+      #
+      # @return [String]
+      #
+      attr_reader :trace_id
+
+      ##
+      # A unique identifier for a span within a trace, assigned when the span
+      # is created. The ID is an 8-byte value represented as a hexadecimal
+      # string.
+      #
+      # @return [String]
+      #
+      attr_reader :span_id
+
+      ##
+      # The `span_id` of this span's parent span. If this is a root span, then
+      # this field must be empty. The ID is an 8-byte value represented as a
+      # hexadecimal string.
+      #
+      # @return [String]
+      #
+      attr_reader :parent_span_id
+
+      ##
+      # The name of this span.
+      #
+      # @return [TruncatableString]
+      #
+      attr_reader :name
+
+      ##
+      # The starting timestamp of this span in UTC.
+      #
+      # @return [Time]
+      #
+      attr_reader :start_time
+
+      ##
+      # The ending timestamp of this span in UTC.
+      #
+      # @return [Time]
+      #
+      attr_reader :end_time
+
+      ##
+      # The properties of this span.
+      #
+      # @return [Hash<String, (TruncatableString, Integer, Boolean)>]
+      #
+      attr_reader :attributes
+
+      ##
+      # 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.
+      attr_reader :dropped_attributes_count
+
+      ##
+      # A stack trace captured at the start of the span.
+      #
+      # @return [Array<Thread::Backtrace::Location>]
+      #
+      attr_reader :stack_trace
+
+      ##
+      # 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.
+      #
+      # @return [Integer]
+      #
+      attr_reader :dropped_frames_count
+
+      ##
+      # The included time events.
+      #
+      # @return [Array<TimeEvent>]
+      #
+      attr_reader :time_events
+
+      ##
+      # The number of dropped annotations in all the included time events.
+      # If the value is 0, then no annotations were dropped.
+      #
+      # @return [Integer]
+      #
+      attr_reader :dropped_annotations_count
+
+      ##
+      # The number of dropped message events in all the included time events.
+      # If the value is 0, then no message events were dropped.
+      #
+      # @return [Integer]
+      #
+      attr_reader :dropped_message_events_count
+
+      ##
+      # The included links.
+      #
+      # @return [Array<Link>]
+      #
+      attr_reader :links
+
+      ##
+      # The number of dropped links after the maximum size was enforced
+      # If the value is 0, then no links were dropped.
+      #
+      # @return [Integer]
+      #
+      attr_reader :dropped_links_count
+
+      ##
+      # An optional final status for this span.
+      #
+      # @return [Status, nil]
+      attr_reader :status
+
+      ##
+      # A highly recommended but not required flag that identifies when a trace
+      # crosses a process boundary. True when the parent_span belongs to the
+      # same process as the current span.
+      #
+      # @return [Boolean]
+      #
+      attr_reader :same_process_as_parent_span
+
+      ##
+      # An optional number of child spans that were generated while this span
+      # was active. If set, allows an implementation to detect missing child
+      # spans.
+      #
+      # @return [Integer, nil]
+      #
+      attr_reader :child_span_count
+
+      ##
+      # Create an empty Span object.
+      #
+      # @private
+      #
+      def initialize trace_id, span_id, name, start_time, end_time,
+                     parent_span_id: nil, attributes: {},
+                     dropped_attributes_count: 0, stack_trace: [],
+                     dropped_frames_count: 0, time_events: [],
+                     dropped_annotations_count: 0,
+                     dropped_message_events_count: 0, links: [],
+                     dropped_links_count: 0, status: nil,
+                     same_process_as_parent_span: true,
+                     child_span_count: nil
+        @name = name
+        @trace_id = trace_id
+        @span_id = span_id
+        @parent_span_id = parent_span_id
+        @start_time = start_time
+        @end_time = end_time
+        @attributes = attributes
+        @dropped_attributes_count = dropped_attributes_count
+        @stack_trace = stack_trace
+        @dropped_frames_count = dropped_frames_count
+        @time_events = time_events
+        @dropped_annotations_count = dropped_annotations_count
+        @dropped_message_events_count = dropped_message_events_count
+        @links = links
+        @dropped_links_count = dropped_links_count
+        @status = status
+        @same_process_as_parent_span = same_process_as_parent_span
+        @child_span_count = child_span_count
+      end
+    end
+  end
+end