redis-time-series 0.1.0 → 0.5.0

data/lib/redis/time_series/aggregation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    # An aggregation is a combination of a mathematical function, and a time window over
+    # which to apply that function. In RedisTimeSeries, aggregations are used to downsample
+    # data from a source series to a destination series, using compaction rules.
+    #
+    # @see Redis::TimeSeries#create_rule
+    # @see Redis::TimeSeries::Rule
+    # @see https://oss.redislabs.com/redistimeseries/commands/#aggregation-compaction-downsampling
+    class Aggregation
+      TYPES = %w[
+        avg
+        count
+        first
+        last
+        max
+        min
+        range
+        std.p
+        std.s
+        sum
+        var.p
+        var.s
+      ]
+
+      # @return [String] the type of aggregation to apply
+      # @see TYPES
+      attr_reader :type
+      alias aggregation_type type
+
+      # @return [Integer] the time window to apply the aggregation over, in milliseconds
+      attr_reader :duration
+      alias time_bucket duration
+
+      # Parse a method argument into an aggregation.
+      #
+      # @param agg [Array, Aggregation] an aggregation object, or an array of type and duration +[:avg, 60000]+
+      # @return [Aggregation] the parsed aggregation, or the original argument if already an aggregation
+      # @raise [AggregationError] when given an unparseable value
+      def self.parse(agg)
+        return unless agg
+        return agg if agg.is_a?(self)
+        return new(agg.first, agg.last) if agg.is_a?(Array) && agg.size == 2
+        raise AggregationError, "Couldn't parse #{agg} into an aggregation rule!"
+      end
+
+      # Create a new Aggregation given a type and duration.
+      # @param type [String, Symbol] one of the valid aggregation {TYPES}
+      # @param duration [Integer, ActiveSupport::Duration]
+      #   A time window to apply this aggregation over.
+      #   If you're using ActiveSupport, duration objects (e.g. +10.minutes+) will be automatically coerced.
+      # @return [Aggregation]
+      # @raise [AggregationError] if the given aggregation type is not valid
+      def initialize(type, duration)
+        type = type.to_s.downcase
+        unless TYPES.include? type
+          raise AggregationError, "#{type} is not a valid aggregation type!"
+        end
+        @type = type
+        if defined?(ActiveSupport::Duration) && duration.is_a?(ActiveSupport::Duration)
+          @duration = duration.in_milliseconds
+        else
+          @duration = duration.to_i
+        end
+      end
+
+      # @api private
+      # @return [Array]
+      def to_a
+        ['AGGREGATION', type, duration]
+      end
+
+      # @api private
+      # @return [String]
+      def to_s
+        to_a.join(' ')
+      end
+
+      # Compares aggregations based on type and duration.
+      # @return [Boolean] whether the given aggregations are equivalent
+      def ==(other)
+        parsed = self.class.parse(other)
+        type == parsed.type && duration == parsed.duration
+      end
+    end
+  end
+end

data/lib/redis/time_series/client.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+using TimeMsec
+
+class Redis
+  class TimeSeries
+    # The client module handles connection management for individual time series, and
+    # the parent {TimeSeries} class methods. You can enable or disable debugging, and set
+    # a default Redis client to use for time series objects.
+    module Client
+      def self.extended(base)
+        base.class_eval do
+          attr_reader :redis
+
+          private
+
+          def cmd(name, *args)
+            self.class.send :cmd_with_redis, redis, name, *args
+          end
+        end
+      end
+
+      # Check debug status. Defaults to on with +DEBUG=true+ environment variable.
+      # @return [Boolean] current debug status
+      def debug
+        @debug.nil? ? [true, 'true', 1].include?(ENV['DEBUG']) : @debug
+      end
+
+      # Enable or disable debug output for time series commands. Enabling debug will
+      # print commands to +STDOUT+ as they're executed.
+      #
+      # @example
+      #   [1] pry(main)> @ts1.get
+      #   => #<Redis::TimeSeries::Sample:0x00007fc82e9de150 @time=2020-07-19 15:01:13 -0700, @value=0.56e2>
+      #   [2] pry(main)> Redis::TimeSeries.debug = true
+      #   => true
+      #   [3] pry(main)> @ts1.get
+      #   DEBUG: TS.GET ts1
+      #    => #<Redis::TimeSeries::Sample:0x00007fc82f11b7b0 @time=2020-07-19 15:01:13 -0700, @value=0.56e2>
+      #
+      # @return [Boolean] new debug status
+      def debug=(bool)
+        @debug = !!bool
+      end
+
+      # @return [Redis] the current Redis client. Defaults to +Redis.current+
+      def redis
+        @redis ||= Redis.current
+      end
+
+      # Set the default Redis client for time series objects.
+      # This may be useful if you already use a non-time-series Redis database, and want
+      # to use both at the same time.
+      #
+      # @example
+      #   # config/initializers/redis_time_series.rb
+      #   Redis::TimeSeries.redis = Redis.new(url: 'redis://my-redis-server:6379/0')
+      #
+      # @param client [Redis] a Redis client
+      # @return [Redis]
+      def redis=(client)
+        @redis = client
+      end
+
+      private
+
+      def cmd(name, *args)
+        cmd_with_redis redis, name, *args
+      end
+
+      def cmd_with_redis(redis, name, *args)
+        args = args.flatten.compact.map { |arg| arg.is_a?(Time) ? arg.ts_msec : arg }
+        puts "DEBUG: #{name} #{args.join(' ')}" if debug
+        redis.call name, args
+      end
+    end
+  end
+end

data/lib/redis/time_series/errors.rb

@@ -0,0 +1,19 @@
+class Redis
+  class TimeSeries
+    # Base error class for convenient +rescue+-ing.
+    #
+    # Descendant of +Redis::BaseError+, so you can rescue that and capture all
+    # time-series errors, as well as standard Redis command errors.
+    class Error < Redis::BaseError; end
+
+    # +FilterError+ is raised when a given set of filters is invalid (i.e. does not contain
+    # a equality comparison "foo=bar"), or the filter value is unparseable.
+    # @see Redis::TimeSeries::Filters
+    class FilterError < Error; end
+
+    # +AggregationError+ is raised when attempting to create an aggreation with
+    # an unknown type, or when calling a command with an invalid aggregation value.
+    # @see Redis::TimeSeries::Aggregation
+    class AggregationError < Error; end
+  end
+end

data/lib/redis/time_series/filters.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    class Filters
+      Equal = Struct.new(:label, :value) do
+        self::REGEX = /^[^!]+=[^(]+/
+
+        def self.parse(str)
+          new(*str.split('='))
+        end
+
+        def to_h
+          { label => value }
+        end
+
+        def to_s
+          "#{label}=#{value}"
+        end
+      end
+
+      NotEqual = Struct.new(:label, :value) do
+        self::REGEX = /^.+!=[^(]+/
+
+        def self.parse(str)
+          new(*str.split('!='))
+        end
+
+        def to_h
+          { label => { not: value } }
+        end
+
+        def to_s
+          "#{label}!=#{value}"
+        end
+      end
+
+      Absent = Struct.new(:label) do
+        self::REGEX = /^[^!]+=$/
+
+        def self.parse(str)
+          new(str.delete('='))
+        end
+
+        def to_h
+          { label => false }
+        end
+
+        def to_s
+          "#{label}="
+        end
+      end
+
+      Present = Struct.new(:label) do
+        self::REGEX = /^.+!=$/
+
+        def self.parse(str)
+          new(str.delete('!='))
+        end
+
+        def to_h
+          { label => true }
+        end
+
+        def to_s
+          "#{label}!="
+        end
+      end
+
+      AnyValue = Struct.new(:label, :values) do
+        self::REGEX = /^[^!]+=\(.+\)/
+
+        def self.parse(str)
+          label, values = str.split('=')
+          values = values.tr('()', '').split(',')
+          new(label, values)
+        end
+
+        def to_h
+          { label => values }
+        end
+
+        def to_s
+          "#{label}=(#{values.map(&:to_s).join(',')})"
+        end
+      end
+
+      NoValues = Struct.new(:label, :values) do
+        self::REGEX = /^.+!=\(.+\)/
+
+        def self.parse(str)
+          label, values = str.split('!=')
+          values = values.tr('()', '').split(',')
+          new(label, values)
+        end
+
+        def to_h
+          { label => { not: values } }
+        end
+
+        def to_s
+          "#{label}!=(#{values.map(&:to_s).join(',')})"
+        end
+      end
+
+      TYPES = [Equal, NotEqual, Absent, Present, AnyValue, NoValues]
+      TYPES.each do |type|
+        define_method "#{type.to_s.split('::').last.gsub(/(.)([A-Z])/,'\1_\2').downcase}" do
+          filters.select { |f| f.is_a? type }
+        end
+      end
+
+      attr_reader :filters
+
+      def initialize(filters = nil)
+        @filters = case filters
+                   when String then parse_string(filters)
+                   when Hash then parse_hash(filters)
+                   else []
+                   end
+      end
+
+      def validate!
+        valid? || raise(FilterError, 'Filtering requires at least one equality comparison')
+      end
+
+      def valid?
+        !!filters.find { |f| f.is_a? Equal }
+      end
+
+      def to_a
+        filters.map(&:to_s)
+      end
+
+      def to_h
+        filters.reduce({}) { |h, filter| h.merge(filter.to_h) }
+      end
+
+      def to_s
+        to_a.join(' ')
+      end
+
+      private
+
+      def parse_string(filter_string)
+        return unless filter_string.is_a? String
+        filter_string.split(' ').map do |str|
+          match = TYPES.find { |f| f::REGEX.match? str }
+          raise(FilterError, "Unable to parse '#{str}'") unless match
+          match.parse(str)
+        end
+      end
+
+      def parse_hash(filter_hash)
+        return unless filter_hash.is_a? Hash
+        filter_hash.map do |label, value|
+          case value
+          when TrueClass then Present.new(label)
+          when FalseClass then Absent.new(label)
+          when Array then AnyValue.new(label, value)
+          when Hash
+            raise(FilterError, "Invalid filter hash value #{value}") unless value.keys === [:not]
+            (v = value.values.first).is_a?(Array) ? NoValues.new(label, v) : NotEqual.new(label, v)
+          else Equal.new(label, value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/redis/time_series/info.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    # The Info struct wraps the result of the +TS.INFO+ command with method access.
+    # It also applies some limited parsing to the result values, mainly snakifying
+    # the property keys, and instantiating Rule objects if necessary.
+    #
+    # All properties of the struct are also available on a TimeSeries object itself
+    # via delegation.
+    #
+    # @!attribute [r] chunk_count
+    #   @return [Integer] number of memory chunks used for the time-series
+    # @!attribute [r] first_timestamp
+    #   @return [Integer] first timestamp present in the time-series (milliseconds since epoch)
+    # @!attribute [r] labels
+    #   @return [Hash] a hash of label-value pairs that represent metadata labels of the time-series
+    # @!attribute [r] last_timestamp
+    #   @return [Integer] last timestamp present in the time-series (milliseconds since epoch)
+    # @!attribute [r] max_samples_per_chunk
+    #   @return [Integer] maximum number of samples per memory chunk
+    # @!attribute [r] memory_usage
+    #   @return [Integer] total number of bytes allocated for the time-series
+    # @!attribute [r] retention_time
+    #   @return [Integer] retention time, in milliseconds, for the time-series.
+    #     A zero value means unlimited retention.
+    # @!attribute [r] rules
+    #   @return [Array<Rule>] an array of configured compaction {Rule}s
+    # @!attribute [r] series
+    #   @return [TimeSeries] the series this info is from
+    # @!attribute [r] source_key
+    #   @return [String, nil] the key of the source series, if this series is the destination
+    #     of a compaction rule
+    # @!attribute [r] total_samples
+    #   @return [Integer] the total number of samples in the series
+    #
+    # @see TimeSeries#info
+    # @see https://oss.redislabs.com/redistimeseries/commands/#tsinfo
+    Info = Struct.new(
+      :chunk_count,
+      :first_timestamp,
+      :labels,
+      :last_timestamp,
+      :max_samples_per_chunk,
+      :memory_usage,
+      :retention_time,
+      :rules,
+      :series,
+      :source_key,
+      :total_samples,
+      keyword_init: true
+    ) do
+      # @api private
+      # @return [Info]
+      def self.parse(series:, data:)
+        data.each_slice(2).reduce({}) do |h, (key, value)|
+          # Convert camelCase info keys to snake_case
+          h[key.gsub(/(.)([A-Z])/,'\1_\2').downcase] = value
+          h
+        end.then do |parsed_hash|
+          parsed_hash['series'] = series
+          parsed_hash['labels'] = parsed_hash['labels'].to_h
+          parsed_hash['rules'] = parsed_hash['rules'].map { |d| Rule.new(source: series, data: d) }
+          new(parsed_hash)
+        end
+      end
+
+      alias count total_samples
+      alias length total_samples
+      alias size total_samples
+
+      # If this series is the destination of a compaction rule, returns the source series of the data.
+      # @return [TimeSeries, nil] the series referred to by {source_key}
+      def source
+        return unless source_key
+        @source ||= TimeSeries.new(source_key, redis: series.redis)
+      end
+    end
+  end
+end

data/lib/redis/time_series/rule.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+class Redis
+  class TimeSeries
+    # A compaction rule applies an aggregation from a source series to a destination series.
+    # As data is added to the source, it will be aggregated based on any configured rule(s) and
+    # distributed to the correct destination(s).
+    #
+    # Compaction rules are useful to retain data over long time periods without requiring exorbitant
+    # amounts of memory and storage. For example, if you're collecting data on a minute-by-minute basis,
+    # you may want to retain a week's worth of data at full fidelity, and a year's worth of data downsampled
+    # to hourly, which would require 60x less memory.
+    class Rule
+      # @return [Aggregation] the configured aggregation for this rule
+      attr_reader :aggregation
+
+      # @return [String] the Redis key of the destination series
+      attr_reader :destination_key
+
+      # @return [TimeSeries] the data source of this compaction rule
+      attr_reader :source
+
+      # Manually instantiating a rule does nothing, don't bother.
+      # @api private
+      # @see Info#rules
+      def initialize(source:, data:)
+        @source = source
+        @destination_key, duration, aggregation_type = data
+        @aggregation = Aggregation.new(aggregation_type, duration)
+      end
+
+      # Delete this compaction rule.
+      # @return [String] the string "OK"
+      def delete
+        source.delete_rule(dest: destination_key)
+      end
+
+      # @return [TimeSeries] the destination time series this rule refers to
+      def destination
+        @dest ||= TimeSeries.new(destination_key, redis: source.redis)
+      end
+      alias dest destination
+
+      # @return [String] the Redis key of the source series
+      def source_key
+        source.key
+      end
+    end
+  end
+end