opencensus 0.4.0 → 0.5.0

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module AggregationData
+      # # LastValue
+      #
+      # Represents the last recorded value.
+      class LastValue
+        # @return [Integer,Float] Last recorded value.
+        attr_reader :value
+
+        # @return [Time] The latest time at new data point was recorded
+        attr_reader :time
+
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        # Set last value
+        # @param [Integer,Float] 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 = value
+        end
+
+        # rubocop:enable Lint/UnusedMethodArgument
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    module AggregationData
+      # Sum
+      #
+      # Accumulate measurement values.
+      class Sum
+        # @return [Integer,Float] The current sum value.
+        attr_reader :value
+
+        # @return [Time] The latest time at new data point was recorded
+        attr_reader :time
+
+        # @private
+        def initialize
+          @value = 0
+        end
+
+        # rubocop:disable Lint/UnusedMethodArgument
+
+        # Add value
+        # @param [Integer,Float] 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 += value
+        end
+
+        # rubocop:enable Lint/UnusedMethodArgument
+      end
+    end
+  end
+end

data/lib/opencensus/stats/config.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# 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/stats/exporters"
+
+module OpenCensus
+  module Stats
+    # Schema of the Trace configuration. See Stats#configure for more info.
+    @config = Common::Config.new do |config|
+      exporter_logger = ::Logger.new STDOUT, ::Logger::INFO
+      default_exporter = Exporters::Logger.new exporter_logger
+
+      config.add_option! :exporter, default_exporter do |value|
+        value.respond_to? :export
+      end
+    end
+
+    # Expose the stats config as a subconfig under the main config.
+    OpenCensus.configure do |config|
+      config.add_alias! :stats, config: @config
+    end
+
+    class << self
+      ##
+      # Configure OpenCensus Stats. These configuration fields include
+      # parameters governing aggregation, exporting.
+      #
+      # This configuration is also available as the `stats` 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.stats`.
+      #
+      # Generally, you should configure this once at process initialization,
+      # but it can be modified at any time.
+      #
+      # Supported fields are:
+      #
+      # *   `exporter` The exporter to use. Must be an exporter, an object with
+      #     an export method that takes an array of ViewData objects. See
+      #     {OpenCensus::Stats::Exporters}. The initial value is a
+      #     {OpenCensus::Stats::Exporters::Logger} that logs to STDOUT.
+      #
+      # @example:
+      #
+      #  OpenCensus::Stats.configure do |config|
+      #    config.exporter = OpenCensus::Stats::Exporters::Logger.new
+      #  end
+      #
+      def configure
+        if block_given?
+          yield @config
+        else
+          @config
+        end
+      end
+
+      ##
+      # Get the current configuration
+      # @private
+      #
+      attr_reader :config
+    end
+  end
+end

data/lib/opencensus/stats/exemplar.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+
+module OpenCensus
+  module Stats
+    ##
+    # Exemplars are example points that may be used to annotate aggregated
+    # Distribution values. They are metadata that gives information about a
+    # particular value added to a Distribution bucket.
+    #
+    class Exemplar
+      # Value of the exemplar point. It determines which bucket the exemplar
+      # belongs to
+      # @return [Integer,Float]
+      attr_reader :value
+
+      # The observation (sampling) time of the above value
+      # @return [Time]
+      attr_reader :time
+
+      # Contextual information about the example value
+      # @return [Hash<String,String>]
+      attr_reader :attachments
+
+      # Create instance of the exemplar
+      # @param [Integer,Float] value
+      # @param [Time] time
+      # @param [Hash<String,String>] attachments. Attachments are key-value
+      #   pairs that describe the context in which the exemplar was recored.
+      def initialize value:, time:, attachments:
+        @value = value
+        @time = time
+
+        raise ArgumentError, "attachments can not be empty" if attachments.nil?
+
+        @attachments = attachments
+      end
+    end
+  end
+end

data/lib/opencensus/stats/exporters.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "opencensus/stats/exporters/logger"
+
+module OpenCensus
+  module Stats
+    ##
+    # The Exporters module provides integrations for exporting collected stats
+    # to an external or local service. Exporter classes may be put inside
+    # this module, but are not required to be located here.
+    #
+    # An exporter is an object that must respond to the following method:
+    #
+    #     def export(views_data)
+    #
+    # Where `views_data` is an array of {OpenCensus::Stats::ViewData} objects
+    # to export.
+    #
+    # The method return value is not defined.
+    #
+    # The exporter object may interpret the `export` message in whatever way it
+    # deems appropriate. For example, it may write the data to a log file, it
+    # may transmit it to a monitoring service, or it may do nothing at all.
+    # An exporter may also queue the request for later asynchronous processing,
+    # and indeed this is recommended if the export involves time consuming
+    # operations such as remote API calls.
+    #
+    module Exporters
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+
+require "logger"
+require "json"
+
+module OpenCensus
+  module Stats
+    module Exporters
+      ##
+      # The Logger exporter exports captured stats view data to a standard
+      # Ruby Logger interface.
+      #
+      class Logger
+        ##
+        # Create a new Logger exporter
+        #
+        # @param [#log] logger The logger to write to.
+        # @param [Integer] level The log level. This should be a log level
+        #        defined by the Logger standard library. Default is
+        #        `::Logger::INFO`.
+        #
+        def initialize logger, level: ::Logger::INFO
+          @logger = logger
+          @level = level
+        end
+
+        ##
+        # Export the captured stats to the configured logger.
+        #
+        # @param [Array<ViewData>] views_data The captured stats data.
+        #
+        def export views_data
+          stats_data = views_data.map { |vd| format_view_data(vd) }
+          @logger.log @level, stats_data.to_json
+          nil
+        end
+
+        private
+
+        def format_view_data view_data
+          {
+            view: format_view(view_data.view),
+            measure: format_measure(view_data.view.measure),
+            aggregation: format_aggregation(view_data)
+          }
+        end
+
+        def format_view view
+          {
+            name: view.name,
+            columns: view.columns,
+            description: view.description
+          }
+        end
+
+        def format_measure measure
+          {
+            name: measure.name,
+            unit: measure.unit,
+            type: measure.type,
+            description: measure.description
+          }
+        end
+
+        def format_aggregation view_data
+          {
+            type: view_data.view.aggregation.class.name.downcase,
+            start_time: view_data.start_time,
+            end_time: view_data.end_time,
+            data: view_data.data
+          }
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/exporters/multi.rb

@@ -0,0 +1,57 @@
+# Copyright 2018 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 "delegate"
+
+module OpenCensus
+  module Stats
+    module Exporters
+      ##
+      # The Multi exporter multiplexes captured stats to a set of delegate
+      # exporters. It is useful if you need to export to more than one
+      # destination. You may also use it as a "null" exporter by providing
+      # no delegates.
+      #
+      # Multi delegates to an array of the exporter objects. You can manage
+      # the list of exporters using any method of Array. For example:
+      #
+      #     multi = OpenCensus::Stats::Exporters::Multi.new
+      #     multi.export(views_data)  # Does nothing
+      #     multi << OpenCensus::Stats::Exporters::Logger.new
+      #     multi.export(views_data)  # Exports to the logger
+      #
+      class Multi < SimpleDelegator
+        ##
+        # Create a new Multi exporter
+        #
+        # @param [Array<#export>] delegates An array of exporters
+        #
+        def initialize *delegates
+          super(delegates.flatten)
+        end
+
+        ##
+        # Pass the captured stats view data to the delegates.
+        #
+        # @param [Array<ViewData>] views_data The captured stats.
+        #
+        def export views_data
+          each { |delegate| delegate.export views_data }
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/opencensus/stats/measure.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+
+require "opencensus/stats/measurement"
+
+module OpenCensus
+  module Stats
+    # Measure
+    #
+    # The definition of the Measurement. Describes the type of the individual
+    # values/measurements recorded by an application. It includes information
+    # such as the type of measurement, the  units of measurement and descriptive
+    # names for the data. This provides th fundamental type used for recording
+    # data.
+    class Measure
+      # Describes the unit used for the Measure.
+      # Should follows the format described by
+      # http://unitsofmeasure.org/ucum.html
+      # Unit name for general counts
+      # @return [String]
+      UNIT_NONE = "1".freeze
+
+      # Unit name for bytes
+      # @return [String]
+      BYTE = "By".freeze
+
+      # Unit name for Kilobytes
+      # @return [String]
+      KBYTE = "kb".freeze
+
+      # Unit name for Seconds
+      # @return [String]
+      SEC = "s".freeze
+
+      # Unit name for Milli seconds
+      # @return [String]
+      MS = "ms".freeze
+
+      # Unit name for Micro seconds
+      # @return [String]
+      US = "us".freeze
+
+      # Unit name for Nano seconds
+      # @return [String]
+      NS = "ns".freeze
+
+      # Measure int64 type
+      # @return [String]
+      INT64_TYPE = "INT64".freeze
+
+      # Measure double type
+      # @return [String]
+      DOUBLE_TYPE = "DOUBLE".freeze
+
+      # @return [String]
+      attr_reader :name
+
+      # @return [String]
+      attr_reader :description
+
+      # Unit type of the measurement. i.e "kb", "ms" etc
+      # @return [String]
+      attr_reader :unit
+
+      # Data type of the measure.
+      # @return [String] Valid types are {INT64_TYPE}, {DOUBLE_TYPE}.
+      attr_reader :type
+
+      # @private
+      # Create instance of the measure.
+      def initialize name:, unit:, type:, description: nil
+        @name = name
+        @unit = unit
+        @type = type
+        @description = description
+      end
+
+      # Create new measurement
+      # @param [Integer, Float] value
+      # @param [Hash<String,String>] tags Tags to which the value is recorded
+      # @return [Measurement]
+      def create_measurement value:, tags:
+        Measurement.new measure: self, value: value, tags: tags
+      end
+
+      # Is int64 data type
+      # @return [Boolean]
+      def int64?
+        type == INT64_TYPE
+      end
+
+      # Is float data type
+      # @return [Boolean]
+      def double?
+        type == DOUBLE_TYPE
+      end
+    end
+  end
+end