ezmetrics 1.2.0 → 2.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0affbdfcda841ffe4eec9105ded5526b13d209ccf0aa564e1b84c91651079d0e
-  data.tar.gz: 8c0f3879ee0f2cedeba7f6b0526f679ef9962e2270c7639837821f226a0f3580
+  metadata.gz: df2d108f37b4f0a5988f72ad465c531d0559ef651c78e3f58aa72f7c9fcc0a3c
+  data.tar.gz: a1b871a56189e2035289a976e508dd437125c8a6bc9fa29dfbb47402096faf1b
 SHA512:
-  metadata.gz: 28d6883722e140005b24071ab637104d6d0e16e22a75fffac734b242fafbb88c1ecdbfd4d4d44a11439a8cbac5d0ad5dcfba705ed26a706f6abb83f55f3f5513
-  data.tar.gz: b02ddcabf2669f9458a21dd37e0495218eedff6f15047c923b81d6fbcd311ce34ed2d27c7ea664a97aebaf806eac653dd4ec09fb3ee526607da796ec4c3a54f2
+  metadata.gz: ad8ce6744522f55b65029bffeb8d56491ce188c29870a5560389ea44795131999bbe6f9d11d3a444831c49c2c0aad2f2b8bca448cdd2c18c5a11ba8d04216889
+  data.tar.gz: 80c76c1709db877c71063650db012b423116232a32f6ff5d9c17262e43e80e8696d4a0fc687b798291551ca5f0f6b84f3f7ae7a635ecad644f09628daf842cd1

data/README.md

@@ -10,6 +10,16 @@ Simple, lightweight and fast metrics aggregation for Rails.
 gem 'ezmetrics'
 ```
 
+## Available metrics
+
+|    Type    |          Aggregate functions      |
+|:----------:|:---------------------------------:|
+| `duration` |  `avg`, `max`, `percentile`       |
+|   `views`  |  `avg`, `max`, `percentile`       |
+|    `db`    |  `avg`, `max`, `percentile`       |
+|  `queries` |  `avg`, `max`, `percentile`       |
+| `requests` | `all`, `2xx`, `3xx`, `4xx`, `5xx` |
+
 ## Usage
 
 ### Getting started
@@ -27,25 +37,25 @@ and stores them for the timeframe you specified, 60 seconds by default.
 You can change the timeframe according to your needs and save the metrics by calling `log` method:
 
 ```ruby
-  # Store the metrics for 60 seconds (default behaviour)
-  EZmetrics.new.log(
-    duration: 100.5,
-    views:    40.7,
-    db:       59.8,
-    queries:  4,
-    status:   200
-  )
+# Store the metrics for 60 seconds (default behaviour)
+EZmetrics.new.log(
+  duration: 100.5,
+  views:    40.7,
+  db:       59.8,
+  queries:  4,
+  status:   200
+)
 ```
 
 ```ruby
-  # Store the metrics for 10 minutes
-  EZmetrics.new(10.minutes).log(
-    duration: 100.5,
-    views:    40.7,
-    db:       59.8,
-    queries:  4,
-    status:   200
-  )
+# Store the metrics for 10 minutes
+EZmetrics.new(10.minutes).log(
+  duration: 100.5,
+  views:    40.7,
+  db:       59.8,
+  queries:  4,
+  status:   200
+)
 ```
 
 ---
@@ -53,13 +63,13 @@ You can change the timeframe according to your needs and save the metrics by cal
 For displaying metrics you need to call `show` method:
 
 ```ruby
-  # Aggregate and show metrics for last 60 seconds (default behaviour)
-  EZmetrics.new.show
+# Aggregate and show metrics for last 60 seconds (default behaviour)
+EZmetrics.new.show
 ```
 
 ```ruby
-  # Aggregate and show metrics for last 10 minutes
-  EZmetrics.new(10.minutes).show
+# Aggregate and show metrics for last 10 minutes
+EZmetrics.new(10.minutes).show
 ```
 
 You can combine these timeframes, for example - store for 10 minutes, display for 5 minutes.
@@ -131,6 +141,47 @@ This will return a hash with the following structure:
 }
 ```
 
+---
+
+If you prefer a single level object - you can change the default output structure by calling `.flatten` before `.show`
+
+```ruby
+EZmetrics.new(1.hour).flatten.show(db: :avg, duration: [:avg, :max])
+```
+
+```ruby
+{
+  db_avg:       182,
+  duration_avg: 205,
+  duration_max: 5171
+}
+```
+
+---
+
+Same for [partitioned aggregation](#partitioning)
+
+```ruby
+EZmetrics.new(1.hour).partition_by(:minute).flatten.show(db: :avg, duration: [:avg, :max])
+```
+
+```ruby
+[
+  {
+    timestamp:    1575242880,
+    db_avg:       387,
+    duration_avg: 477,
+    duration_max: 8566
+  },
+  {
+    timestamp:    1575242940,
+    db_avg:       123,
+    duration_avg: 234,
+    duration_max: 3675
+  }
+]
+```
+
 ### Aggregation
 
 The aggregation can be easily configured by specifying aggregation options as in the following examples:
@@ -217,13 +268,57 @@ EZmetrics.new.show(views: :avg, :db: [:avg, :max], requests: true)
 }
 ```
 
+---
+
+**5. Percentile**
+
+This feature is available since version `2.0.0`.
+
+By default percentile aggregation is turned off because it requires to store each value of all metrics.
+
+To enable this feature - you need to set `store_each_value: true` when saving the metrics:
+
+```ruby
+EZmetrics.new.log(
+  duration:         100.5,
+  views:            40.7,
+  db:               59.8,
+  queries:          4,
+  status:           200,
+  store_each_value: true
+)
+```
+
+The aggregation syntax has the following format `metrics_type: :percentile_{number}` where `number` is any integer in the 1..99 range.
+
+
+```ruby
+EZmetrics.new.show(db: [:avg, :percentile_90, :percentile_95], duration: :percentile_99)
+```
+
+```ruby
+{
+  db: {
+    avg: 155,
+    percentile_90: 205,
+    percentile_95: 215
+  },
+  duration: {
+    percentile_99: 236
+  }
+}
+```
+
+
 ### Partitioning
 
-To aggregate metrics, partitioned by a unit of time you need to call `partition_by({time_unit})` before calling `show`
+If you want to visualize your metrics by using a **line chart**, you will need to use partitioning.
+
+To aggregate metrics, partitioned by a unit of time you need to call `.partition_by({time_unit})` before calling `.show`
 
 ```ruby
-  # Aggregate metrics for last hour, partition by minute
-  EZmetrics.new(1.hour).partition_by(:minute).show(duration: [:avg, :max], db: :avg)
+# Aggregate metrics for last hour, partition by minute
+EZmetrics.new(1.hour).partition_by(:minute).show(duration: [:avg, :max], db: :avg)
 ```
 
 This will return an array of objects with the following structure:
@@ -274,6 +369,8 @@ Available time units for partitioning: `second`, `minute`, `hour`, `day`. Defaul
 
 The aggregation speed relies on the performance of **Redis** (data storage) and **Oj** (json serialization/parsing).
 
+#### Simple aggregation
+
 You can check the **aggregation** time by running:
 
 ```ruby
@@ -283,10 +380,10 @@ EZmetrics::Benchmark.new.measure_aggregation
 | Interval | Duration (seconds) |
 | :------: | :----------------: |
 | 1 minute |        0.0         |
-|  1 hour  |        0.04        |
-| 12 hours |        0.49        |
-| 24 hours |        1.51        |
-| 48 hours |        3.48        |
+|  1 hour  |        0.02        |
+| 12 hours |        0.22        |
+| 24 hours |        0.61        |
+| 48 hours |        1.42        |
 
 ---
 
@@ -299,9 +396,44 @@ EZmetrics::Benchmark.new.measure_aggregation(:minute)
 | Interval | Duration (seconds) |
 | :------: | :----------------: |
 | 1 minute |        0.0         |
-|  1 hour  |        0.05        |
-| 12 hours |        0.74        |
-| 24 hours |        2.12        |
-| 48 hours |        4.85        |
+|  1 hour  |        0.02        |
+| 12 hours |        0.25        |
+| 24 hours |        0.78        |
+| 48 hours |        1.75        |
+
+---
+
+#### Percentile aggregation
+
+You can check the **percentile aggregation** time by running:
+
+```ruby
+EZmetrics::Benchmark.new(true).measure_aggregation
+```
+
+| Interval | Duration (seconds) |
+| :------: | :----------------: |
+| 1 minute |        0.0         |
+|  1 hour  |        0.14        |
+| 12 hours |        2.11        |
+| 24 hours |        5.85        |
+| 48 hours |        14.1        |
+
+---
+
+To check the **partitioned aggregation** time for percentile you need to run:
+
+```ruby
+EZmetrics::Benchmark.new(true).measure_aggregation(:minute)
+```
+
+| Interval | Duration (seconds) |
+| :------: | :----------------: |
+| 1 minute |        0.0         |
+|  1 hour  |        0.16        |
+| 12 hours |        1.97        |
+| 24 hours |        5.85        |
+| 48 hours |        13.9        |
+
 
 The benchmarks above were run on a _2017 Macbook Pro 2.9 GHz Intel Core i7 with 16 GB of RAM_

data/lib/ezmetrics.rb

@@ -9,16 +9,18 @@ class EZmetrics
 
   def initialize(interval_seconds=60)
     @interval_seconds = interval_seconds.to_i
-    @redis            = Redis.new
+    @redis            = Redis.new(driver: :hiredis)
+    @schema           = redis_schema
   end
 
-  def log(payload={duration: 0.0, views: 0.0, db: 0.0, queries: 0, status: 200})
+  def log(payload={duration: 0.0, views: 0.0, db: 0.0, queries: 0, status: 200, store_each_value: false})
     @safe_payload = {
-      duration: payload[:duration].to_f,
-      views:    payload[:views].to_f,
-      db:       payload[:db].to_f,
-      queries:  payload[:queries].to_i,
-      status:   payload[:status].to_i
+      duration:         payload[:duration].to_f,
+      views:            payload[:views].to_f,
+      db:               payload[:db].to_f,
+      queries:          payload[:queries].to_i,
+      status:           payload[:status].to_i,
+      store_each_value: payload[:store_each_value].to_s == "true"
     }
 
     this_second          = Time.now.to_i
@@ -31,10 +33,11 @@ class EZmetrics
       METRICS.each do |metrics_type|
         update_sum(metrics_type)
         update_max(metrics_type)
+        store_value(metrics_type) if safe_payload[:store_each_value]
       end
 
-      this_second_metrics["statuses"]["all"]        += 1
-      this_second_metrics["statuses"][status_group] += 1
+      this_second_metrics[schema["all"]]        += 1
+      this_second_metrics[schema[status_group]] += 1
     else
       @this_second_metrics = {
         "second"       => this_second,
@@ -46,10 +49,25 @@ class EZmetrics
         "db_max"       => safe_payload[:db],
         "queries_sum"  => safe_payload[:queries],
         "queries_max"  => safe_payload[:queries],
-        "statuses"     => { "2xx" => 0, "3xx" => 0, "4xx" => 0, "5xx" => 0, "all" => 1 }
+        "2xx"          => 0,
+        "3xx"          => 0,
+        "4xx"          => 0,
+        "5xx"          => 0,
+        "all"          => 1
       }
 
-      this_second_metrics["statuses"][status_group] = 1
+      if safe_payload[:store_each_value]
+        this_second_metrics.merge!(
+          "duration_values" => [safe_payload[:duration]],
+          "views_values"    => [safe_payload[:views]],
+          "db_values"       => [safe_payload[:db]],
+          "queries_values"  => [safe_payload[:queries]]
+        )
+      end
+
+      this_second_metrics[status_group] = 1
+
+      @this_second_metrics = this_second_metrics.values
     end
 
     redis.setex(this_second, interval_seconds, Oj.dump(this_second_metrics))
@@ -63,20 +81,25 @@ class EZmetrics
     partitioned_metrics ? aggregate_partitioned_data : aggregate_data
   end
 
+  def flatten
+    @flat = true
+    self
+  end
+
   def partition_by(time_unit=:minute)
     time_unit = PARTITION_UNITS.include?(time_unit) ? time_unit : :minute
-    @partitioned_metrics = interval_metrics.group_by { |h| second_to_partition_unit(time_unit, h["second"]) }
+    @partitioned_metrics = interval_metrics.group_by { |array| second_to_partition_unit(time_unit, array[schema["second"]]) }
     self
   end
 
   private
 
-  attr_reader :redis, :interval_seconds, :interval_metrics, :requests,
+  attr_reader :redis, :interval_seconds, :interval_metrics, :requests, :flat, :schema,
     :storage_key, :safe_payload, :this_second_metrics, :partitioned_metrics, :options
 
   def aggregate_data
     return {} unless interval_metrics.any?
-    @requests = interval_metrics.sum { |hash| hash["statuses"]["all"] }
+    @requests = interval_metrics.sum { |array| array[schema["all"]] }
     build_result
   rescue
     {}
@@ -85,17 +108,20 @@ class EZmetrics
   def aggregate_partitioned_data
     partitioned_metrics.map do |partition, metrics|
       @interval_metrics = metrics
-      @requests = interval_metrics.sum { |hash| hash["statuses"]["all"] }
-      { timestamp: partition, data: build_result }
+      @requests = interval_metrics.sum { |array| array[schema["all"]] }
+      METRICS.each { |metrics_type| instance_variable_set("@sorted_#{metrics_type}_values", nil) }
+      flat ? { timestamp: partition, **build_result } : { timestamp: partition, data: build_result }
     end
   rescue
-    new(options)
+    self
   end
 
   def build_result
     result = {}
 
-    result[:requests] = { all: requests, grouped: count_all_status_groups } if options[:requests]
+    if options[:requests]
+      append_requests_to_result(result, { all: requests, grouped: count_all_status_groups })
+    end
 
     options.each do |metrics, aggregation_functions|
       next unless METRICS.include?(metrics)
@@ -103,8 +129,8 @@ class EZmetrics
       next unless aggregation_functions.any?
 
       aggregation_functions.each do |aggregation_function|
-        result[metrics] ||= {}
-        result[metrics][aggregation_function] = aggregate(metrics, aggregation_function)
+        aggregated_metrics = aggregate(metrics, aggregation_function)
+        append_metrics_to_result(result, metrics, aggregation_function, aggregated_metrics)
       end
     end
     result
@@ -112,51 +138,129 @@ class EZmetrics
     result
   end
 
+  def append_requests_to_result(result, aggregated_requests)
+    return result[:requests] = aggregated_requests unless flat
+
+    result[:requests_all] = aggregated_requests[:all]
+    aggregated_requests[:grouped].each do |group, counter|
+      result[:"requests_#{group}"] = counter
+    end
+  end
+
+  def append_metrics_to_result(result, metrics, aggregation_function, aggregated_metrics)
+    return result[:"#{metrics}_#{aggregation_function}"] = aggregated_metrics if flat
+
+    result[metrics] ||= {}
+    result[metrics][aggregation_function] = aggregated_metrics
+  end
+
   def second_to_partition_unit(time_unit, second)
     return second if time_unit == :second
-    time_unit_depth = { minute: 4, hour: 3, day: 2 }
-    reset_depth     = time_unit_depth[time_unit]
-    time_to_array   = Time.at(second).to_a[0..5].reverse
-    Time.new(*time_to_array[0..reset_depth]).to_i
+    time = Time.at(second)
+    return (time - time.sec - time.min * 60 - time.hour * 3600).to_i if time_unit == :day
+    return (time - time.sec - time.min * 60).to_i                    if time_unit == :hour
+    (time - time.sec).to_i
   end
 
   def interval_metrics
     @interval_metrics ||= begin
       interval_start    = Time.now.to_i - interval_seconds
       interval_keys     = (interval_start..Time.now.to_i).to_a
-      redis.mget(interval_keys).compact.map { |hash| Oj.load(hash) }
+      redis.mget(interval_keys).compact.map { |array| Oj.load(array) }
     end
   end
 
   def aggregate(metrics, aggregation_function)
-    return unless AGGREGATION_FUNCTIONS.include?(aggregation_function)
     return avg("#{metrics}_sum") if aggregation_function == :avg
     return max("#{metrics}_max") if aggregation_function == :max
+
+    percentile = aggregation_function.match(/percentile_(?<value>\d+)/)
+
+    if percentile && percentile["value"].to_i.between?(1, 99)
+      sorted_values = send("sorted_#{metrics}_values")
+      percentile(sorted_values, percentile["value"].to_i)
+    end
+  end
+
+  METRICS.each do |metrics|
+    define_method "sorted_#{metrics}_values" do
+      instance_variable_get("@sorted_#{metrics}_values") || instance_variable_set(
+        "@sorted_#{metrics}_values", interval_metrics.map { |array| array[schema["#{metrics}_values"]] }.flatten.compact.sort
+      )
+    end
+  end
+
+  def redis_schema
+    [
+      "second",
+      "duration_sum",
+      "duration_max",
+      "views_sum",
+      "views_max",
+      "db_sum",
+      "db_max",
+      "queries_sum",
+      "queries_max",
+      "2xx",
+      "3xx",
+      "4xx",
+      "5xx",
+      "all",
+      "duration_values",
+      "views_values",
+      "db_values",
+      "queries_values"
+    ].each_with_index.inject({}){ |result, pair| result[pair[0]] = pair[1] ; result }
   end
 
   def update_sum(metrics)
-    this_second_metrics["#{metrics}_sum"] += safe_payload[metrics]
+    this_second_metrics[schema["#{metrics}_sum"]] += safe_payload[metrics]
+  end
+
+  def store_value(metrics)
+    this_second_metrics[schema["#{metrics}_values"]] << safe_payload[metrics]
   end
 
   def update_max(metrics)
-    max_value = [safe_payload[metrics], this_second_metrics["#{metrics}_max"]].max
-    this_second_metrics["#{metrics}_max"] = max_value
+    max_value = [safe_payload[metrics], this_second_metrics[schema["#{metrics}_max"]]].max
+    this_second_metrics[schema["#{metrics}_max"]] = max_value
   end
 
   def avg(metrics)
-    (interval_metrics.sum { |h| h[metrics] }.to_f / requests).round
+    (interval_metrics.sum { |array| array[schema[metrics]] }.to_f / requests).round
   end
 
   def max(metrics)
-    interval_metrics.max { |h| h[metrics] }[metrics].round
+    interval_metrics.max { |array| array[schema[metrics]] }[schema[metrics]].round
+  end
+
+  def percentile(sorted_array, pcnt)
+    array_length = sorted_array.length
+
+    return "not enough data (requests: #{array_length}, required: #{pcnt})" if array_length < pcnt
+
+    rank  = (pcnt.to_f / 100) * (array_length + 1)
+    whole = rank.truncate
+
+    # if has fractional part
+    if whole != rank
+      s0 = sorted_array[whole - 1]
+      s1 = sorted_array[whole]
+
+      f = (rank - rank.truncate).abs
+
+      return ((f * (s1 - s0)) + s0)&.round
+    else
+      return (sorted_array[whole - 1])&.round
+    end
   end
 
   def count_all_status_groups
-    interval_metrics.inject({ "2xx" => 0, "3xx" => 0, "4xx" => 0, "5xx" => 0 }) do |result, h|
-      result["2xx"] += h["statuses"]["2xx"]
-      result["3xx"] += h["statuses"]["3xx"]
-      result["4xx"] += h["statuses"]["4xx"]
-      result["5xx"] += h["statuses"]["5xx"]
+    interval_metrics.inject({ "2xx" => 0, "3xx" => 0, "4xx" => 0, "5xx" => 0 }) do |result, array|
+      result["2xx"] += array[schema["2xx"]]
+      result["3xx"] += array[schema["3xx"]]
+      result["4xx"] += array[schema["4xx"]]
+      result["5xx"] += array[schema["5xx"]]
       result
     end
   end

data/lib/ezmetrics/benchmark.rb

@@ -2,12 +2,13 @@ require "benchmark"
 
 class EZmetrics::Benchmark
 
-  def initialize
-    @start      = Time.now.to_i
-    @redis      = Redis.new
-    @durations  = []
-    @iterations = 3
-    @intervals  = {
+  def initialize(store_each_value=false)
+    @store_each_value = store_each_value
+    @start            = Time.now.to_i
+    @redis            = Redis.new(driver: :hiredis)
+    @durations        = []
+    @iterations       = 1
+    @intervals        = {
       "1.minute" => 60,
       "1.hour  " => 3600,
       "12.hours" => 43200,
@@ -29,31 +30,38 @@ class EZmetrics::Benchmark
 
   private
 
-  attr_reader :start, :redis, :durations, :intervals, :iterations
+  attr_reader :start, :redis, :durations, :intervals, :iterations, :store_each_value
 
   def write_metrics
     seconds = intervals.values.max
     seconds.times do |i|
       second = start - i
       payload = {
-        "second"          => second,
-        "duration_sum"    => rand(10000),
-        "duration_max"    => rand(10000),
-        "views_sum"       => rand(1000),
-        "views_max"       => rand(1000),
-        "db_sum"          => rand(8000),
-        "db_max"          => rand(8000),
-        "queries_sum"     => rand(100),
-        "queries_max"     => rand(100),
-        "statuses"        => {
-          "2xx" => rand(1..10),
-          "3xx" => rand(1..10),
-          "4xx" => rand(1..10),
-          "5xx" => rand(1..10),
-          "all" => rand(1..40)
-        }
+        "second"       => second,
+        "duration_sum" => rand(10000),
+        "duration_max" => rand(10000),
+        "views_sum"    => rand(1000),
+        "views_max"    => rand(1000),
+        "db_sum"       => rand(8000),
+        "db_max"       => rand(8000),
+        "queries_sum"  => rand(100),
+        "queries_max"  => rand(100),
+        "2xx"          => rand(1..10),
+        "3xx"          => rand(1..10),
+        "4xx"          => rand(1..10),
+        "5xx"          => rand(1..10),
+        "all"          => rand(1..40)
       }
-      redis.setex(second, seconds, Oj.dump(payload))
+
+      if store_each_value
+        payload.merge!(
+          "duration_values" => Array.new(100) { rand(10..60000) },
+          "views_values"    => Array.new(100) { rand(10..60000) },
+          "db_values"       => Array.new(100) { rand(10..60000) },
+          "queries_values"  => Array.new(10)  { rand(1..60) }
+        )
+      end
+      redis.setex(second, seconds, Oj.dump(payload.values))
     end
     nil
   end
@@ -67,10 +75,11 @@ class EZmetrics::Benchmark
   def measure_aggregation_time(interval, seconds, partition_by)
     iterations.times do
       durations << ::Benchmark.measure do
-        if partition_by
-          EZmetrics.new(seconds).partition_by(partition_by).show
+        ezmetrics = EZmetrics.new(seconds)
+        if store_each_value
+          partition_by ? ezmetrics.partition_by(partition_by).show(db: :percentile_90) : ezmetrics.show(db: :percentile_90)
         else
-          EZmetrics.new(seconds).show
+          partition_by ? ezmetrics.partition_by(partition_by).show : ezmetrics.show
         end
       end.real
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ezmetrics
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.2
 platform: ruby
 authors:
 - Nicolae Rotaru
@@ -76,11 +76,10 @@ files:
 - README.md
 - lib/ezmetrics.rb
 - lib/ezmetrics/benchmark.rb
-homepage: https://nyku.github.io/ezmetrics
+homepage: https://github.com/nyku/ezmetrics
 licenses:
 - GPL-3.0
-metadata:
-  source_code_uri: https://github.com/nyku/ezmetrics
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths: