opencensus 0.4.0 → 0.5.0

data/lib/opencensus/stats/measure_registry.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+
+require "singleton"
+require "opencensus/stats/measure"
+
+module OpenCensus
+  module Stats
+    # #MeasureRegistry
+    #
+    # Measure registry is a collection of uniq measures.
+    #
+    class MeasureRegistry
+      include Singleton
+
+      # @return [Hash<String, Measure>]
+      attr_reader :measures
+
+      # @private
+      def initialize
+        @measures = {}
+      end
+
+      class << self
+        # Register measure.
+        #
+        # @param [String] name Name of measure
+        # @param [String] unit Unit name of measure
+        # @param [String] type Date type unit of measure. integer or float.
+        # @param [String] description Description of measure
+        # @return [Measure, nil]
+        #
+        def register name:, unit:, type:, description: nil
+          return if instance.measures.key? name
+
+          measure = Measure.new(
+            name: name,
+            unit: unit,
+            type: type,
+            description: description
+          )
+
+          instance.measures[name] = measure
+        end
+
+        # Un register measure
+        #
+        # @param [String] name Name of the registered view
+        def unregister name
+          instance.measures.delete name
+        end
+
+        # Clear measures registry
+        def clear
+          instance.measures.clear
+        end
+
+        # Get registered measure
+        # @return [Measure]
+        def get name
+          instance.measures[name]
+        end
+
+        # List of registered measures
+        # @return [Array<Measure>]
+        def measures
+          instance.measures.values
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/measurement.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    # Measurement
+    #
+    # Describes a data point to be collected for a Measure.
+    class Measurement
+      # @return [Measure] A measure to which the value is applied.
+      attr_reader :measure
+
+      # @return [Integer,Float] The recorded value
+      attr_reader :value
+
+      # @return [TagMap] The tags to which the value is applied
+      attr_reader :tags
+
+      # @return [Time] The time when measurement was created.
+      attr_reader :time
+
+      # Create a instance of measurement
+      #
+      # @param [Measure] measure A measure to which the value is applied.
+      # @param [Integer,Float] value Measurement value.
+      # @param [Hash<String,String>] tags The tags to which the value is applied
+      def initialize measure:, value:, tags:
+        @measure = measure
+        @value = value
+        @tags = Tags::TagMap.new tags
+        @time = Time.now.utc
+      end
+    end
+  end
+end

data/lib/opencensus/stats/recorder.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+
+require "opencensus/stats/view"
+require "opencensus/stats/view_data"
+
+module OpenCensus
+  module Stats
+    # Stats recorder.
+    #
+    # Recorder record measurement against measure for registered views.
+    class Recorder
+      # @private
+      # @return [Hash<String,View>] Hash of view name and View object.
+      attr_reader :views
+
+      # @private
+      # @return [Hash<String,Measure>] Hash of measure name and Measure object.
+      attr_reader :measures
+
+      # @private
+      # @return [Hash<String,Array<<ViewData>>]
+      # Hash of view name and View data objects array.
+      attr_reader :measure_views_data
+
+      # @private
+      # Create instance of the recorder.
+      def initialize
+        @views = {}
+        @measures = {}
+        @measure_views_data = {}
+        @time = Time.now.utc
+      end
+
+      # Register view
+      #
+      # @param [View] view
+      # @return [View]
+      def register_view view
+        return if @views.key? view.name
+
+        @views[view.name] = view
+        @measures[view.measure.name] = view.measure
+
+        unless @measure_views_data.key? view.measure.name
+          @measure_views_data[view.measure.name] = []
+        end
+
+        @measure_views_data[view.measure.name] << ViewData.new(
+          view,
+          start_time: @time,
+          end_time: @time
+        )
+        view
+      end
+
+      # Record measurements
+      #
+      # @param [Array<Measurement>, Measurement] measurements
+      # @param [Hash<String,String>] attachments
+      def record *measurements, attachments: nil
+        return if measurements.any? { |m| m.value < 0 }
+
+        measurements.each do |measurement|
+          views_data = @measure_views_data[measurement.measure.name]
+          next unless views_data
+
+          views_data.each do |view_data|
+            view_data.record measurement, attachments: attachments
+          end
+        end
+      end
+
+      # Get recorded data for given view name
+      #
+      # @param [String] view_name View name
+      # @return [ViewData]
+      def view_data view_name
+        view = @views[view_name]
+        return unless view
+
+        views_data = @measure_views_data[view.measure.name]
+        views_data.find { |view_data| view_data.view.name == view.name }
+      end
+
+      # Get all views data list
+      # @return [Array<ViewData>]
+      def views_data
+        @measure_views_data.values.flatten
+      end
+
+      # Clear recorded stats.
+      def clear_stats
+        @measure_views_data.each_value do |views_data|
+          views_data.each(&:clear)
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/view.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    # View
+    #
+    # A View specifies an aggregation and a set of tag keys.
+    # The aggregation will be broken down by the unique set of matching tag
+    # values for each measure.
+    class View
+      # @return [String] Name of the view
+      attr_reader :name
+
+      # @return [Measure] Associated measure definition instance.
+      attr_reader :measure
+
+      # @return [Aggregation] Associated aggregation definition instance.
+      attr_reader :aggregation
+
+      # Columns (a.k.a Tag Keys) to match with the
+      # associated Measure. Measure will be recorded in a "greedy" way.
+      # That is, every view aggregates every measure.
+      # This is similar to doing a GROUPBY on view columns. Columns must be
+      # unique.
+      # @return [Array<String>]
+      attr_reader :columns
+
+      # @return [String] Detailed description
+      attr_reader :description
+
+      # @return [Time] View creation time.
+      attr_reader :time
+
+      # Create instance of the view
+      #
+      # @param [String] name
+      # @param [Measure] measure
+      # @param [Aggregation] aggregation
+      # @param [Array<String>] columns
+      # @param [String] description
+      def initialize \
+          name:,
+          measure:,
+          aggregation:,
+          columns:,
+          description: nil
+        @name = name
+        @measure = measure
+        @aggregation = aggregation
+        @columns = columns
+        @description = description
+        @time = Time.now.utc
+      end
+    end
+  end
+end

data/lib/opencensus/stats/view_data.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    # ViewData is a container to store stats.
+    class ViewData
+      # @return [View]
+      attr_reader :view
+
+      # @return [Time, nil]
+      attr_reader :start_time
+
+      # @return [Time, nil]
+      attr_reader :end_time
+
+      # @return [Hash<Array<String>>,AggregationData] Recorded stats data
+      # against view columns.
+      attr_reader :data
+
+      # @private
+      # Create instance of view
+      #
+      # @param [View] view
+      # @param [Time] start_time
+      # @param [Time] end_time
+      def initialize view, start_time: nil, end_time: nil
+        @view = view
+        @start_time = start_time
+        @end_time = end_time
+        @data = {}
+      end
+
+      # Set start time.
+      def start
+        @start_time = Time.now.utc
+      end
+
+      # Set stop time.
+      def stop
+        @end_time = Time.now.utc
+      end
+
+      # Record a measurement.
+      #
+      # @param [Measurement] measurement
+      # @param [Hash<String,String>] attachments
+      def record measurement, attachments: nil
+        tag_values = @view.columns.map { |column| measurement.tags[column] }
+
+        unless @data.key? tag_values
+          @data[tag_values] = @view.aggregation.create_aggregation_data
+        end
+
+        @data[tag_values].add(
+          measurement.value,
+          measurement.time,
+          attachments: attachments
+        )
+      end
+
+      # Clear recorded ata
+      def clear
+        data.clear
+      end
+    end
+  end
+end

data/lib/opencensus/tags.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Copyright 2017 OpenCensus Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,14 +15,49 @@
 # limitations under the License.
 
 
+require "opencensus/tags/config"
+require "opencensus/tags/tag_map"
+require "opencensus/tags/formatters"
+
 module OpenCensus
   ##
   # The Tags module contains support for OpenCensus tags. Tags are key-value
   # pairs. Tags provide additional cardinality to the OpenCensus instrumentation
   # data.
   #
-  # TODO: implement tags
-  #
   module Tags
+    ##
+    # Internal key for storing the current TagMap in the thread local
+    # Context
+    #
+    # @private
+    #
+    TAG_MAP_CONTEXT_KEY = :__tag_map_context__
+
+    class << self
+      ##
+      # Sets the current thread-local TagMap, which used in Stats data
+      # recording.
+      #
+      # @param [TagMap] context
+      #
+      def tag_map_context= context
+        OpenCensus::Context.set TAG_MAP_CONTEXT_KEY, context
+      end
+
+      # Unsets the current thread-local TagMap context
+      #
+      def unset_tag_map_context
+        OpenCensus::Context.unset TAG_MAP_CONTEXT_KEY
+      end
+
+      # Returns the current thread-local TagMap object.
+      #
+      # @return [TagMap, nil]
+      #
+      def tag_map_context
+        OpenCensus::Context.get TAG_MAP_CONTEXT_KEY
+      end
+    end
   end
 end

data/lib/opencensus/tags/config.rb

@@ -0,0 +1,74 @@
+# 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/config"
+require "opencensus/tags/formatters"
+
+module OpenCensus
+  module Tags
+    # Schema of the Tags configuration. See Tags#configure for more info.
+    @config = Common::Config.new do |config|
+      default_formatter = Formatters::Binary.new
+      config.add_option! :binary_formatter, default_formatter do |value|
+        value.respond_to?(:serialize) && value.respond_to?(:deserialize)
+      end
+    end
+
+    # Expose the tags config as a subconfig under the main config.
+    OpenCensus.configure do |config|
+      config.add_alias! :tags, config: @config
+    end
+
+    class << self
+      ##
+      # Configure OpenCensus Tags. These configuration fields include
+      # parameters formatter.
+      #
+      # This configuration is also available as the `tags` subconfig under the
+      # main configuration `OpenCensus.configure`. If the OpenCensus Railtie is
+      # installed in a Rails application, the configuration object is also
+      # exposed as `config.opencensus.tags`.
+      #
+      # Generally, you should configure this once at process initialization,
+      # but it can be modified at any time.
+      #
+      # Supported fields are:
+      #
+      # *  `binary_formatter` The tags context propagation formatter to use.
+      #    Must be a formatter, an object with `serialize`, `deserialize`,
+      #    methods. See {OpenCensus::Tags::Formatters::Binary}.
+      #
+      # @example
+      #
+      #   OpenCensus::Tags.configure do |config|
+      #     config.binary_formatter = OpenCensus::Tags::Formatters::Binary.new
+      #   end
+      #
+      def configure
+        if block_given?
+          yield @config
+        else
+          @config
+        end
+      end
+
+      ##
+      # Get the current configuration
+      # @private
+      #
+      attr_reader :config
+    end
+  end
+end