ddtelemetry 1.0.0a1 → 1.0.0a2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 410462bde4ad03647c35d4eb9706a513e8453e74d2218e9d60cc2f19b0a8f935
-  data.tar.gz: 8392f095624dc46eb70c463fdbf9e004fad56c273670eb54e650ae044140d101
+  metadata.gz: 4fb967335678607cb86deb8c2b48446735a957230cb9349ce3858d21233d002b
+  data.tar.gz: eadc2b1b9a1737564dbd38abc68f4a59c320d5cdbeb13ed3d0df0fe7c5c3a3f3
 SHA512:
-  metadata.gz: 8fc60025054933c5f5b07a0d72bb3c457c67016324ce9670d6eee63b952f8ab5cdc0fd4cd85bdc92dc5e82b0f44eff69272137c7b1087b5aba9e6321afeca423
-  data.tar.gz: 34e45164626c7ec0b40382ac3c1fe4fd020a412c12b8903a93c34fac557210ef87045d69664de4a8198798d4be2d93433535ee3243da2613723efc28cf422663
+  metadata.gz: 1474fb4050d596b8f1fed72f80760e63e37f42a99327c9acdd57d7af5afe3139f096f8067437ca5d297c52ea3d4847117aeacb8ffc8d9b142f753f47495491e9
+  data.tar.gz: 6ac9b71a55dd640a652a762c6974a6260a7448cfc94d1a30cd4f23a340a75237b7fba521049228a5ebc0b3287837434da604224253f6df693d8162e2bba3262f

data/Gemfile

@@ -10,6 +10,6 @@ group :devel do
   gem 'rake'
   gem 'rspec'
   gem 'rspec-its'
-  gem 'rubocop', '~> 0.50'
+  gem 'rubocop', '~> 0.52'
   gem 'timecop', '~> 0.9'
 end

data/NEWS.md

@@ -1,5 +1,11 @@
 # DDTelemetry news
 
+## 1.0.0a2 (2017-12-18)
+
+Changes:
+
+* Many API changes to make usage simpler
+
 ## 1.0.0a1 (2017-12-02)
 
 Initial release.

data/README.md

@@ -6,9 +6,7 @@
 
 # DDTelemetry
 
-_DDTelemetry_ provides in-process, non-timeseries telemetry for short-running Ruby processes.
-
-⚠️ This project is **experimental** and should not be used in production yet.
+_DDTelemetry_ is a Ruby library for recording and analysing measurements in short-running Ruby processes.
 
 If you are looking for a full-featured timeseries monitoring system, look no further than [Prometheus](https://prometheus.io/).
 
@@ -32,28 +30,30 @@ class Cache
 end
 ```
 
-To start instrumenting this code, require `ddtelemetry`, pass a telemetry instance into the constructor, and record some metrics:
+To start instrumenting this code, require `ddtelemetry`, create a counter, and record some metrics:
 
 ```ruby
 require 'ddtelemetry'
 
 class Cache
-  def initialize(telemetry)
-    @telemetry = telemetry
+  attr_reader :counter
+
+  def initialize
     @map = {}
+    @counter = DDTelemetry::Counter.new
   end
 
   def []=(key, value)
-    @telemetry.counter(:cache).increment(:set)
+    @counter.increment(:set)
 
     @map[key] = value
   end
 
   def [](key)
     if @map.key?(key)
-      @telemetry.counter(:cache).increment([:get, :hit])
+      @counter.increment(:get_hit)
     else
-      @telemetry.counter(:cache).increment([:get, :miss])
+      @counter.increment(:get_miss)
     end
 
     @map[key]
@@ -61,11 +61,10 @@ class Cache
 end
 ```
 
-Let’s construct a cache (with telemetry) and exercise it:
+Let’s construct a cache and exercise it:
 
 ```ruby
-telemetry = DDTelemetry::Registry.new
-cache = Cache.new(telemetry)
+cache = Cache.new
 
 cache['greeting']
 cache['greeting']
@@ -75,17 +74,26 @@ cache['greeting']
 cache['greeting']
 ```
 
-Finally, print the recorded telemetry values:
+Finally, get the recorded telemetry values:
 
 ```ruby
-p telemetry.counter(:cache).value(:set)
-# => 1
+cache.counter.get(:set)      # => 1
+cache.counter.get(:get_hit)  # => 3
+cache.counter.get(:get_miss) # => 2
+```
 
-p telemetry.counter(:cache).value([:get, :hit])
-# => 3
+Or even print all stats:
 
-p telemetry.counter(:cache).value([:get, :miss])
-# => 2
+```ruby
+puts cache.counter
+```
+
+```
+         │ count
+─────────┼──────
+get_miss │     2
+     set │     1
+ get_hit │     3
 ```
 
 ## Installation
@@ -106,7 +114,122 @@ Or install it yourself as:
 
 ## Usage
 
-TODO
+_DDTelemetry_ provides two metric types:
+
+* A **counter** is an integer metric that only ever increases. Examples: cache hits, number of files written, …
+
+* A **summary** records observations, and provides functionality for describing the distribution of the observations through quantiles. Examples: outgoing request durations, size of written files, …
+
+Each metric is recorded with a label, which is a free-form object that is useful to further refine the kind of data that is being recorded. For example:
+
+```ruby
+cache_hits_counter.increment(:file_cache)
+request_durations_summary.observe(:weather_api, 1.07)
+```
+
+NOTE: Labels will likely change to become key-value pairs in a future version of DDTelemetry.
+
+### Counters
+
+To create a counter, instantiate `DDTelemetry::Counter`:
+
+```ruby
+counter = DDTelemetry::Counter.new
+```
+
+To increment a counter, call `#increment` with a label:
+
+```ruby
+counter.increment(:file_cache)
+```
+
+To get the value for a certain label, use `#get`:
+
+```ruby
+counter.get(:file_cache)
+# => 1
+```
+
+### Summaries
+
+To create a summary, instantiate `DDTelemetry::Summary`:
+
+```ruby
+summary = DDTelemetry::Summary.new
+```
+
+To observe a value, call `#observe` with a label, along with the value to observe:
+
+```ruby
+summary.observe(:weather_api, 0.88)
+summary.observe(:weather_api, 1.07)
+summary.observe(:weather_api, 0.91)
+```
+
+To get the list of observations for a certain label, use `#get`, which will return a `DDTelemetry::Stats` instance:
+
+```ruby
+summary.get(:weather_api)
+# => <DDTelemetry::Stats>
+```
+
+The following methods are available on `DDTelemetry::Stats`:
+
+* `#count`: returns the number of values
+* `#sum`: returns the sum of all values
+* `#avg`: returns the average of all values
+* `#min`: returns the minimum value
+* `#max`: returns the maximum value
+* `#quantile(fraction)`: returns the quantile at the given fraction (0.0 – 1.0)
+
+### Printing metrics
+
+To print a metric, use `#to_s`. For example:
+
+```ruby
+summary = DDTelemetry::Summary.new
+
+summary.observe(2.1, :erb)
+summary.observe(4.1, :erb)
+summary.observe(5.3, :haml)
+
+puts summary
+```
+
+Output:
+
+```
+     │ count    min    .50    .90    .95    max    tot
+─────┼────────────────────────────────────────────────
+ erb │     2   2.10   3.10   3.90   4.00   4.10   6.20
+haml │     1   5.30   5.30   5.30   5.30   5.30   5.30
+```
+
+### Stopwatch
+
+The `DDTelemetry::Stopwatch` class can be used to measure durations. Use `#start` and `#stop` to start and stop the stopwatch, respectively, and `#duration` to read the value of the stopwatch:
+
+```ruby
+stopwatch = DDTelemetry::Stopwatch.new
+
+stopwatch.start
+sleep 1
+stopwatch.stop
+puts "That took #{stopwatch.duration}s."
+# Output: That took 1.006831s.
+```
+
+A stopwatch, once created, will never reset its duration. Running the stopwatch again will add to the existing duration:
+
+```ruby
+stopwatch.start
+sleep 1
+stopwatch.stop
+puts "That took #{stopwatch.duration}s."
+# Output: That took 2.012879s.
+```
+
+You can query whether or not a stopwatch is running using `#running?`; `#stopped?` is the opposite of `#running?`.
 
 ## Development
 

data/Rakefile

@@ -7,8 +7,12 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.verbose = false
 end
 
+task :test_samples do
+  sh 'bundle exec ruby samples/cache.rb > /dev/null'
+end
+
 RuboCop::RakeTask.new(:rubocop)
 
 task default: :test
 
-task test: %i[spec rubocop]
+task test: %i[spec rubocop test_samples]

data/lib/ddtelemetry.rb

@@ -3,18 +3,17 @@
 require_relative 'ddtelemetry/version'
 
 module DDTelemetry
-  def self.new
-    Registry.new
-  end
 end
 
+require_relative 'ddtelemetry/basic_counter'
+require_relative 'ddtelemetry/basic_summary'
+
+require_relative 'ddtelemetry/metric'
 require_relative 'ddtelemetry/counter'
 require_relative 'ddtelemetry/summary'
 
-require_relative 'ddtelemetry/labelled_counter'
-require_relative 'ddtelemetry/labelled_summary'
-
-require_relative 'ddtelemetry/registry'
 require_relative 'ddtelemetry/stopwatch'
 
 require_relative 'ddtelemetry/table'
+require_relative 'ddtelemetry/printer'
+require_relative 'ddtelemetry/stats'

data/lib/ddtelemetry/basic_counter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DDTelemetry
+  class BasicCounter
+    attr_reader :value
+
+    def initialize
+      @value = 0
+    end
+
+    def increment
+      @value += 1
+    end
+  end
+end

data/lib/ddtelemetry/basic_summary.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module DDTelemetry
+  class BasicSummary
+    attr_reader :values
+
+    def initialize
+      @values = []
+    end
+
+    def observe(value)
+      @values << value
+    end
+  end
+end

data/lib/ddtelemetry/counter.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
 module DDTelemetry
-  class Counter
-    attr_reader :value
+  class Counter < Metric
+    def increment(label)
+      basic_metric_for(label, BasicCounter).increment
+    end
 
-    def initialize
-      @value = 0
+    def get(label)
+      basic_metric_for(label, BasicCounter).value
     end
 
-    def increment
-      @value += 1
+    def to_s
+      DDTelemetry::Printer.new.counter_to_s(self)
     end
   end
 end

data/lib/ddtelemetry/metric.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DDTelemetry
+  class Metric
+    include Enumerable
+
+    def initialize
+      @basic_metrics = {}
+    end
+
+    def get(label)
+      basic_metric_for(label, BasicCounter)
+    end
+
+    def labels
+      @basic_metrics.keys
+    end
+
+    def each
+      @basic_metrics.each_key do |label|
+        yield(label, get(label))
+      end
+    end
+
+    # @api private
+    def basic_metric_for(label, basic_class)
+      @basic_metrics.fetch(label) { @basic_metrics[label] = basic_class.new }
+    end
+  end
+end

data/lib/ddtelemetry/printer.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module DDTelemetry
+  class Printer
+    def summary_to_s(summary)
+      DDTelemetry::Table.new(table_for_summary(summary)).to_s
+    end
+
+    def counter_to_s(counter)
+      DDTelemetry::Table.new(table_for_counter(counter)).to_s
+    end
+
+    private
+
+    def table_for_summary(summary)
+      headers = ['', 'count', 'min', '.50', '.90', '.95', 'max', 'tot']
+
+      rows = summary.labels.map do |label|
+        stats = summary.get(label)
+
+        count = stats.count
+        min   = stats.min
+        p50   = stats.quantile(0.50)
+        p90   = stats.quantile(0.90)
+        p95   = stats.quantile(0.95)
+        tot   = stats.sum
+        max   = stats.max
+
+        [label.to_s, count.to_s] + [min, p50, p90, p95, max, tot].map { |r| format('%4.2f', r) }
+      end
+
+      [headers] + rows
+    end
+
+    def table_for_counter(counter)
+      headers = ['', 'count']
+
+      rows = counter.labels.map do |label|
+        [label.to_s, counter.get(label).to_s]
+      end
+
+      [headers] + rows
+    end
+  end
+end

data/lib/ddtelemetry/stats.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module DDTelemetry
+  class Stats
+    class EmptyError < StandardError
+      def message
+        'Not enough data to perform calculation'
+      end
+    end
+
+    def initialize(values)
+      @values = values
+    end
+
+    def inspect
+      "<#{self.class} count=#{count}>"
+    end
+
+    def count
+      @values.size
+    end
+
+    def sum
+      raise EmptyError if @values.empty?
+      @values.reduce(:+)
+    end
+
+    def avg
+      sum.to_f / count
+    end
+
+    def min
+      quantile(0.0)
+    end
+
+    def max
+      quantile(1.0)
+    end
+
+    def quantile(fraction)
+      raise EmptyError if @values.empty?
+
+      target = (@values.size - 1) * fraction.to_f
+      interp = target % 1.0
+      sorted_values[target.floor] * (1.0 - interp) + sorted_values[target.ceil] * interp
+    end
+
+    private
+
+    def sorted_values
+      @sorted_values ||= @values.sort
+    end
+  end
+end