redis-time-series 0.2.0 → 0.5.2

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

@@ -1,29 +1,84 @@
 # 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(
-      :total_samples,
-      :memory_usage,
+      :chunk_count,
+      :chunk_size,
+      :chunk_type,
+      :duplicate_policy,
       :first_timestamp,
+      :labels,
       :last_timestamp,
-      :retention_time,
-      :chunk_count,
       :max_samples_per_chunk,
-      :labels,
-      :source_key,
+      :memory_usage,
+      :retention_time,
       :rules,
+      :series,
+      :source_key,
+      :total_samples,
       keyword_init: true
     ) do
-      def self.parse(raw_array)
-        raw_array.each_slice(2).reduce({}) do |h, (key, value)|
+      # @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
+          key = key.gsub(/(.)([A-Z])/,'\1_\2').downcase.to_sym
+          next h unless members.include?(key)
+          h[key] = value
           h
         end.then do |parsed_hash|
-          parsed_hash['labels'] = parsed_hash['labels'].to_h
+          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

data/lib/redis/time_series/sample.rb

@@ -1,23 +1,39 @@
 # frozen_string_literal: true
 class Redis
   class TimeSeries
+    # A sample is an immutable value object that represents a single data point within a time series.
     class Sample
-      TS_FACTOR = 1000.0
+      using TimeMsec
 
-      attr_reader :time, :value
+      # @return [Time] the sample's timestamp
+      attr_reader :time
+      # @return [BigDecimal] the decimal value of the sample
+      attr_reader :value
 
+      # Samples are returned by time series query methods, there's no need to create one yourself.
+      # @api private
+      # @see TimeSeries#get
+      # @see TimeSeries#range
       def initialize(timestamp, value)
-        @time = Time.at(timestamp / TS_FACTOR)
+        @time = Time.from_msec(timestamp)
         @value = BigDecimal(value)
       end
 
-      def ts_msec
-        (time.to_f * TS_FACTOR).to_i
+      # @return [Integer] the millisecond value of the sample's timestamp
+      # @note
+      #   We're wrapping the method provided by the {TimeMsec} refinement for convenience,
+      #   otherwise it wouldn't be callable on {time} and devs would have to litter
+      #   +using TimeMsec+ or +* 1000.0+ wherever they wanted the value.
+      def to_msec
+        time.ts_msec
       end
 
+      # @return [Hash] a hash representation of the sample
+      # @example
+      #   {:timestamp=>1595199272401, :value=>0.2e1}
       def to_h
         {
-          timestamp: ts_msec,
+          timestamp: to_msec,
           value: value
         }
       end