opencensus 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 536fa079d66a3bb4bef7a0e70439d5e9cc016f25e86e775a74d7426c4ef3a7e7
-  data.tar.gz: '00688752f3c40bd18f08d4b0f311b8bd16435798647b1c09b70ad3c9240fb233'
+  metadata.gz: 91a03df4a06baad585ee01c05d653eb296bb5903e848d989fa125a32061d891c
+  data.tar.gz: 1b298783443b3eb906f902c3f1e8662fa2833b6845d40674c0efa251d64ae02d
 SHA512:
-  metadata.gz: 50ef3104c577f850c1b4dc8b7bbe9da6030eab510f413c9cec5934da88f0b80232a97b77b7a50f5997925b53601f8796089ab7587c011bb28f2cf593171f37ea
-  data.tar.gz: 8f4735b8955070ea7cbec12fd9260fe0a6f0647c0702837e7e74691e05b8f8bebaf2e7be92b3065b89e865cc2d2b4f100cf8ff2b6a2a1e57dceafbd9e9746da4
+  metadata.gz: 6bc52a99df66952372a72f157e1aace46eeaa167f31f3156639b1ad41637180e2b649352020b32a66cfcaa660c6dae59148e68bc6112491af4de89246333ad08
+  data.tar.gz: 21e637f7efa756f846a4ca847b673d947804aa6446821782ad60eed3bf75862170470b1e6e51f7e7475916728838b1bb2de933c9f1a894e963a56b74488773ce

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Release History
 
+### 0.5.0 / 2019-10-14
+
+This update brings experimental support for the OpenCensus Stats API. Note that
+Stats support is currently partial and not well-tested.
+
+Other changes:
+
+* Attributes in the Trace API can now be floats.
+
 ### 0.4.0 / 2018-10-22
 
 This is an important update that includes a number of fixes and brings the

data/README.md

@@ -8,7 +8,8 @@ the core OpenCensus APIs and basic integrations with Rails, Faraday, and GRPC.
 Additional integrations, including exporters to popular analytics services,
 will be available in separate gems.
 
-The library is in alpha stage, and the API is subject to change.
+The library is in alpha stage, and the API is subject to change. In particular,
+support for the Stats API is currently incomplete and experimental.
 
 ## Quick Start
 

data/lib/opencensus/stats.rb

@@ -13,6 +13,13 @@
 # limitations under the License.
 
 
+require "opencensus/stats/config"
+require "opencensus/stats/recorder"
+require "opencensus/stats/view"
+require "opencensus/stats/aggregation"
+require "opencensus/stats/measure_registry"
+require "opencensus/stats/exporters"
+
 module OpenCensus
   ##
   # The Stats module contains support for OpenCensus stats collection.
@@ -20,8 +27,143 @@ module OpenCensus
   # OpenCensus allows users to create typed measures, record measurements,
   # aggregate the collected data, and export the aggregated data.
   #
-  # TODO: implement stats
   #
   module Stats
+    ##
+    # Internal key for storing the current stats recorder in the thread local
+    # context.
+    #
+    # @private
+    RECORDER_CONTEXT_KEY = :__recorder_context__
+
+    class << self
+      ##
+      # Sets the current thread-local Recorder, which governs the behavior
+      # of the recorder creation methods of OpenCensus::Stats::Recorder.
+      #
+      # @param [Recorder] context
+      def recorder_context= context
+        OpenCensus::Context.set RECORDER_CONTEXT_KEY, context
+      end
+
+      ##
+      # Unsets the current thread-local SpanContext, disabling stats recorder
+      # creation methods of OpenCensus::Stats::Recorder
+      def unset_recorder_context
+        OpenCensus::Context.unset RECORDER_CONTEXT_KEY
+      end
+
+      # Get the current thread-local stats recorder context/
+      # Returns `nil` if there is no current SpanContext.
+      #
+      # @return [Recorder, nil]
+      def recorder_context
+        OpenCensus::Context.get RECORDER_CONTEXT_KEY
+      end
+
+      # Get recorder from the stats context. If stats context nil then create
+      # new recorder and set into stats context.
+      # @return [Recorder]
+      def ensure_recorder
+        self.recorder_context ||= Recorder.new
+      end
+
+      # Create and register int64 type measure into measure registry.
+      #
+      # @param [String] name Name of the measure.
+      # @param [String] unit Unit of the measure. i.e "kb", "s", "ms"
+      # @param [String] description Detail description
+      # @return [Measure]
+      def create_measure_int name:, unit:, description: nil
+        MeasureRegistry.register(
+          name: name,
+          unit: unit,
+          type: Measure::INT64_TYPE,
+          description: description
+        )
+      end
+
+      # Create and register double type measure into measure registry.
+      #
+      # @param [String] name Name of the measure.
+      # @param [String] unit Unit of the measure. i.e "kb", "s", "ms"
+      # @param [String] description Detail description
+      # @return [Measure]
+      def create_measure_double name:, unit:, description: nil
+        MeasureRegistry.register(
+          name: name,
+          unit: unit,
+          type: Measure::DOUBLE_TYPE,
+          description: description
+        )
+      end
+
+      # Get list of registered measures
+      # @return [Array<Measure>]
+      def registered_measures
+        MeasureRegistry.measures
+      end
+
+      # Create measurement value for registered measure.
+      #
+      # @param [String] name Name of the registered measure
+      # @param [Integer, Float] value Value of the measurement
+      # @param [Hash<String,String>] tags Tags to which the value is recorded
+      # @raise [ArgumentError] if givem measure is not register
+      def create_measurement name:, value:, tags:
+        measure = MeasureRegistry.get name
+        return measure.create_measurement(value: value, tags: tags) if measure
+        raise ArgumentError, "#{name} measure is not registered"
+      end
+
+      # Create and register a view to current stats recorder context.
+      #
+      # @param [String] name
+      # @param [Measure] measure
+      # @param [Aggregation] aggregation
+      # @param [Array<String>] columns
+      # @param [String] description
+      def create_and_register_view \
+          name:,
+          measure:,
+          aggregation:,
+          columns: nil,
+          description: nil
+        view = View.new(
+          name: name,
+          measure: measure,
+          aggregation: aggregation,
+          description: description,
+          columns: columns
+        )
+        ensure_recorder.register_view view
+      end
+
+      # Create aggregation defination instance with type sum.
+      # @return [Aggregation]
+      def create_sum_aggregation
+        Aggregation::Sum.new
+      end
+
+      # Create aggregation defination instance with type count.
+      # @return [Aggregation]
+      def create_count_aggregation
+        Aggregation::Count.new
+      end
+
+      # Create aggregation defination instance with type distribution.
+      # @param [Array<Integer>,Array<Float>] buckets Value boundries for
+      # distribution.
+      # @return [Aggregation]
+      def create_distribution_aggregation buckets
+        Aggregation::Distribution.new buckets
+      end
+
+      # Create aggregation defination instance with type last value.
+      # @return [Aggregation]
+      def create_last_value_aggregation
+        Aggregation::LastValue.new
+      end
+    end
   end
 end

data/lib/opencensus/stats/aggregation.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+
+require "opencensus/stats/aggregation/sum"
+require "opencensus/stats/aggregation/count"
+require "opencensus/stats/aggregation/last_value"
+require "opencensus/stats/aggregation/distribution"
+require "opencensus/stats/aggregation_data"
+require "opencensus/stats/exemplar"
+
+module OpenCensus
+  module Stats
+    # # Aggregation
+    #
+    # Aggregation types to describes how the data collected based on aggregation
+    # type.
+    # Aggregation types are.
+    # - Sum
+    # - Count
+    # - Last Value
+    # - Distribution - calcualate min, max, mean, sum, count,
+    #   sum of squared deviation
+    #
+    module Aggregation
+    end
+  end
+end

data/lib/opencensus/stats/aggregation/count.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module Aggregation
+      # Count aggregation type
+      class Count
+        # Create new aggregation data container to store count value.
+        # values.
+        # @return [AggregationData::Count]
+        def create_aggregation_data
+          AggregationData::Count.new
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/aggregation/distribution.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module Aggregation
+      # Distribution aggregation type
+      class Distribution
+        # Invalid bucket types.
+        class InvalidBucketsError < StandardError; end
+
+        # @return [Array<Integer>,Array<Float>] Bucket boundries.
+        attr_reader :buckets
+
+        # @private
+        # @param [Array<Integer>,Array<Float>,] buckets Buckets boundries
+        # for distribution
+        # aggregation.
+        # @raise [InvalidBucketsError] If any bucket value is nil.
+        def initialize buckets
+          if buckets.nil? || buckets.empty?
+            raise InvalidBucketsError, "buckets should not be nil or empty"
+          end
+
+          if buckets.any?(&:nil?)
+            raise InvalidBucketsError, "buckets value should not be nil"
+          end
+
+          @buckets = buckets.reject { |v| v < 0 }
+        end
+
+        # Create new aggregation data container to store distribution values.
+        # values.
+        # @return [AggregationData::Distribution]
+        def create_aggregation_data
+          AggregationData::Distribution.new @buckets
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/aggregation/last_value.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module Aggregation
+      # Last value aggregation type
+      class LastValue
+        # Create new aggregation data container to store last value.
+        # values.
+        # @return [AggregationData::LastValue]
+        def create_aggregation_data
+          AggregationData::LastValue.new
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/aggregation/sum.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module Aggregation
+      # Sum aggregation type
+      class Sum
+        # Create new aggregation data container to store sum value
+        # values.
+        # @return [AggregationData::Sum]
+        def create_aggregation_data
+          AggregationData::Sum.new
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/aggregation_data.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+
+require "opencensus/stats/aggregation_data/sum"
+require "opencensus/stats/aggregation_data/count"
+require "opencensus/stats/aggregation_data/last_value"
+require "opencensus/stats/aggregation_data/distribution"
+
+module OpenCensus
+  module Stats
+    # # AggregationData
+    #
+    # AggregationData to store collected stats data.
+    # Aggregation data container type:
+    # - Sum
+    # - Count
+    # - Last Value
+    # - Distribution - calcualate sum, count, min, max, mean,
+    #   sum of squared deviation
+    #
+    module AggregationData
+    end
+  end
+end

data/lib/opencensus/stats/aggregation_data/count.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module AggregationData
+      # # Count
+      #
+      # Counts number of measurements recorded.
+      class Count
+        # @return [Integer,Float] Current count value.
+        attr_reader :value
+
+        # @return [Time] The latest timestamp a new data point was recorded
+        attr_reader :time
+
+        # @private
+        def initialize
+          @value = 0
+        end
+
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        # Increment counter.
+        # @param [Value] value
+        # @param [Time] time Time of data point was recorded
+        # @param [Hash<String,String>] attachments Attachments are not in use.
+        def add value, time, attachments: nil
+          @time = time
+          @value += 1
+        end
+
+        # rubocop:enable Lint/UnusedMethodArgument
+      end
+    end
+  end
+end

data/lib/opencensus/stats/aggregation_data/distribution.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module AggregationData
+      # # Distribution
+      #
+      # This AggregationData contains a histogram of the collected values
+      class Distribution
+        # @return [Array<Integer>,Array<Float>] Buckets boundries
+        attr_reader :buckets
+
+        # @return [Integer] Count of recorded values
+        attr_reader :count
+
+        # @return [Integer,Float] Sum of recorded values
+        attr_reader :sum
+
+        # @return [Integer,Float] Maximum recorded value
+        attr_reader :max
+
+        # @return [Integer,Float] Minimum recorded value
+        attr_reader :min
+
+        # @return [Integer,Float] Mean of recorded values
+        attr_reader :mean
+
+        # @return [Integer,Float] Sum of squared deviation of recorded values
+        attr_reader :sum_of_squared_deviation
+
+        # @return [Array<Integer>] Count of number of recorded values in buckets
+        attr_reader :bucket_counts
+
+        # @return [Time] Time of first recorded value
+        attr_reader :start_time
+
+        # @return [Time] The latest time a new value was recorded
+        attr_reader :time
+
+        # @return [Array<Exemplar>] Exemplars are points associated with each
+        #   bucket in the distribution giving an example of what was aggregated
+        #   into the bucket.
+        attr_reader :exemplars
+
+        # @private
+        # @param [Array<Integer>,Array<Float>] buckets Buckets boundries
+        # for distribution
+        def initialize buckets
+          @buckets = buckets
+          @count = 0
+          @sum = 0
+          @max = -Float::INFINITY
+          @min = Float::INFINITY
+          @mean = 0
+          @sum_of_squared_deviation = 0
+          @bucket_counts = Array.new(buckets.length + 1, 0)
+          @exemplars = []
+          @start_time = Time.now.utc
+        end
+
+        # @private
+        # Add value to distribution
+        # @param [Integer,Float] value
+        # @param [Time] time Time of data point was recorded
+        # @param [Hash<String,String>,nil] attachments Attachments are key-value
+        #   pairs that describe the context in which the exemplar was recored.
+        def add value, time, attachments: nil
+          @time = time
+          @count += 1
+          @sum += value
+          @max = value if value > @max
+          @min = value if value < @min
+
+          delta_from_mean = (value - @mean).to_f
+          @mean += delta_from_mean / @count
+          @sum_of_squared_deviation += delta_from_mean * (value - @mean)
+
+          bucket_index = @buckets.find_index { |b| b > value } ||
+                         @buckets.length
+          @bucket_counts[bucket_index] += 1
+
+          if attachments
+            @exemplars[bucket_index] = Exemplar.new(
+              value: value,
+              time: time,
+              attachments: attachments
+            )
+          end
+        end
+
+        # Get distribution result values.
+        # @return [Hash]
+        def value
+          {
+            start_time: @start_time,
+            count: @count,
+            sum: @sum,
+            max: @max,
+            min: @min,
+            sum_of_squared_deviation: @sum_of_squared_deviation,
+            buckets: @buckets,
+            bucket_counts: @bucket_counts
+          }
+        end
+      end
+    end
+  end
+end