ddtelemetry 1.0.0a1 → 1.0.0a2

data/lib/ddtelemetry/stopwatch.rb

@@ -2,8 +2,6 @@
 
 module DDTelemetry
   class Stopwatch
-    attr_reader :duration
-
     class AlreadyRunningError < StandardError
       def message
         'Cannot start, because stopwatch is already running'
@@ -16,6 +14,12 @@ module DDTelemetry
       end
     end
 
+    class StillRunningError < StandardError
+      def message
+        'Cannot get duration, because stopwatch is still running'
+      end
+    end
+
     def initialize
       @duration = 0.0
       @last_start = nil
@@ -32,6 +36,11 @@ module DDTelemetry
       @last_start = nil
     end
 
+    def duration
+      raise StillRunningError if running?
+      @duration
+    end
+
     def running?
       !@last_start.nil?
     end

data/lib/ddtelemetry/summary.rb

@@ -1,55 +1,18 @@
 # frozen_string_literal: true
 
 module DDTelemetry
-  class Summary
-    class EmptySummaryError < StandardError
-      def message
-        'Cannot calculate quantile for empty summary'
-      end
+  class Summary < Metric
+    def observe(value, label)
+      basic_metric_for(label, BasicSummary).observe(value)
     end
 
-    def initialize
-      @values = []
+    def get(label)
+      values = basic_metric_for(label, BasicSummary).values
+      DDTelemetry::Stats.new(values)
     end
 
-    def observe(value)
-      @values << value
-      @sorted_values = nil
-    end
-
-    def count
-      @values.size
-    end
-
-    def sum
-      raise EmptySummaryError if @values.empty?
-      @values.reduce(:+)
-    end
-
-    def avg
-      sum / count
-    end
-
-    def min
-      quantile(0.0)
-    end
-
-    def max
-      quantile(1.0)
-    end
-
-    def quantile(fraction)
-      raise EmptySummaryError 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
+    def to_s
+      DDTelemetry::Printer.new.summary_to_s(self)
     end
   end
 end

data/lib/ddtelemetry/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DDTelemetry
-  VERSION = '1.0.0a1'
+  VERSION = '1.0.0a2'
 end

data/roadmap.md

@@ -0,0 +1,7 @@
+## Roadmap
+
+This document details the changes need to get to a stable 1.0.
+
+*   **Don’t use the term “telemetry”:** The term “telemetry” specifically refers to collecting data from remote systems. DDTelemetry does not at all collect from remote systems (in fact, that is explicitly out-of-scope). Suggestion: DDMetrics?
+
+*   **Key-value labels:** Labels can currently be any object. Stabilising on key-value labels, with keys being symbols and labels being strings, would make it easier to create tooling around transforming and analysing datasets that are produced by DDTelemetry.

data/samples/cache.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'ddtelemetry'
+
+class Cache
+  attr_reader :counter
+
+  def initialize
+    @map = {}
+    @counter = DDTelemetry::Counter.new
+  end
+
+  def []=(key, value)
+    @counter.increment(:set)
+
+    @map[key] = value
+  end
+
+  def [](key)
+    if @map.key?(key)
+      @counter.increment(:get_hit)
+    else
+      @counter.increment(:get_miss)
+    end
+
+    @map[key]
+  end
+end
+
+cache = Cache.new
+
+cache['greeting']
+cache['greeting']
+cache['greeting'] = 'Hi there!'
+cache['greeting']
+cache['greeting']
+cache['greeting']
+
+p cache.counter.get(:set)
+# => 1
+
+p cache.counter.get(:get_hit)
+# => 3
+
+p cache.counter.get(:get_miss)
+# => 2
+
+puts cache.counter

data/spec/ddtelemetry/basic_counter_spec.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+describe DDTelemetry::BasicCounter do
+  subject(:counter) { described_class.new }
+
+  it 'starts at 0' do
+    expect(counter.value).to eq(0)
+  end
+
+  describe '#increment' do
+    subject { counter.increment }
+
+    it 'increments' do
+      expect { subject }
+        .to change { counter.value }
+        .from(0)
+        .to(1)
+    end
+  end
+end

data/spec/ddtelemetry/basic_summary_spec.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+describe DDTelemetry::BasicSummary do
+  subject(:summary) { described_class.new }
+
+  context 'no observations' do
+    its(:values) { is_expected.to be_empty }
+  end
+
+  context 'one observation' do
+    before { subject.observe(2.1) }
+    its(:values) { is_expected.to eq([2.1]) }
+  end
+
+  context 'two observations' do
+    before do
+      subject.observe(2.1)
+      subject.observe(4.1)
+    end
+
+    its(:values) { is_expected.to eq([2.1, 4.1]) }
+  end
+end

data/spec/ddtelemetry/counter_spec.rb

@@ -3,18 +3,99 @@
 describe DDTelemetry::Counter do
   subject(:counter) { described_class.new }
 
-  it 'starts at 0' do
-    expect(counter.value).to eq(0)
+  describe 'new counter' do
+    it 'starts at 0' do
+      expect(subject.get(:erb)).to eq(0)
+      expect(subject.get(:haml)).to eq(0)
+    end
   end
 
   describe '#increment' do
-    subject { counter.increment }
+    subject { counter.increment(:erb) }
 
-    it 'increments' do
+    it 'increments the matching value' do
       expect { subject }
-        .to change { counter.value }
+        .to change { counter.get(:erb) }
         .from(0)
         .to(1)
     end
+
+    it 'does not increment any other value' do
+      expect(counter.get(:haml)).to eq(0)
+      expect { subject }
+        .not_to change { counter.get(:haml) }
+    end
+  end
+
+  describe '#get' do
+    subject { counter.get(:erb) }
+
+    context 'not incremented' do
+      it { is_expected.to eq(0) }
+    end
+
+    context 'incremented' do
+      before { counter.increment(:erb) }
+      it { is_expected.to eq(1) }
+    end
+
+    context 'other incremented' do
+      before { counter.increment(:haml) }
+      it { is_expected.to eq(0) }
+    end
+  end
+
+  describe '#labels' do
+    subject { counter.labels }
+
+    before do
+      counter.increment(:erb)
+      counter.increment(:erb)
+      counter.increment(:haml)
+    end
+
+    it { is_expected.to contain_exactly(:haml, :erb) }
+  end
+
+  describe '#each' do
+    subject do
+      {}.tap do |res|
+        counter.each { |label, count| res[label] = count }
+      end
+    end
+
+    before do
+      counter.increment(:erb)
+      counter.increment(:erb)
+      counter.increment(:haml)
+    end
+
+    it { is_expected.to eq(haml: 1, erb: 2) }
+
+    it 'is enumerable' do
+      expect(counter.map { |_label, count| count }.sort)
+        .to eq([1, 2])
+    end
+  end
+
+  describe '#to_s' do
+    subject { counter.to_s }
+
+    before do
+      counter.increment(:erb)
+      counter.increment(:erb)
+      counter.increment(:haml)
+    end
+
+    it 'returns table' do
+      expected = <<~TABLE
+             │ count
+        ─────┼──────
+         erb │     2
+        haml │     1
+      TABLE
+
+      expect(subject.strip).to eq(expected.strip)
+    end
   end
 end

data/spec/ddtelemetry/stats_spec.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+describe DDTelemetry::Stats do
+  subject(:stats) { described_class.new(values) }
+
+  context 'no values' do
+    let(:values) { [] }
+
+    it 'errors on #min' do
+      expect { subject.min }
+        .to raise_error(DDTelemetry::Stats::EmptyError)
+    end
+
+    it 'errors on #max' do
+      expect { subject.max }
+        .to raise_error(DDTelemetry::Stats::EmptyError)
+    end
+
+    it 'errors on #avg' do
+      expect { subject.avg }
+        .to raise_error(DDTelemetry::Stats::EmptyError)
+    end
+
+    it 'errors on #sum' do
+      expect { subject.sum }
+        .to raise_error(DDTelemetry::Stats::EmptyError)
+    end
+
+    its(:count) { is_expected.to eq(0) }
+  end
+
+  context 'one value' do
+    let(:values) { [2.1] }
+
+    its(:inspect) { is_expected.to eq('<DDTelemetry::Stats count=1>') }
+    its(:count) { is_expected.to eq(1) }
+    its(:sum) { is_expected.to eq(2.1) }
+    its(:avg) { is_expected.to eq(2.1) }
+    its(:min) { is_expected.to eq(2.1) }
+    its(:max) { is_expected.to eq(2.1) }
+
+    it 'has proper quantiles' do
+      expect(subject.quantile(0.00)).to eq(2.1)
+      expect(subject.quantile(0.25)).to eq(2.1)
+      expect(subject.quantile(0.50)).to eq(2.1)
+      expect(subject.quantile(0.90)).to eq(2.1)
+      expect(subject.quantile(0.99)).to eq(2.1)
+    end
+  end
+
+  context 'two values' do
+    let(:values) { [2.1, 4.1] }
+
+    its(:inspect) { is_expected.to eq('<DDTelemetry::Stats count=2>') }
+    its(:count) { is_expected.to be_within(0.000001).of(2) }
+    its(:sum) { is_expected.to be_within(0.000001).of(6.2) }
+    its(:avg) { is_expected.to be_within(0.000001).of(3.1) }
+    its(:min) { is_expected.to be_within(0.000001).of(2.1) }
+    its(:max) { is_expected.to be_within(0.000001).of(4.1) }
+
+    it 'has proper quantiles' do
+      expect(subject.quantile(0.00)).to be_within(0.000001).of(2.1)
+      expect(subject.quantile(0.25)).to be_within(0.000001).of(2.6)
+      expect(subject.quantile(0.50)).to be_within(0.000001).of(3.1)
+      expect(subject.quantile(0.90)).to be_within(0.000001).of(3.9)
+      expect(subject.quantile(0.99)).to be_within(0.000001).of(4.08)
+    end
+  end
+
+  context 'integer values' do
+    let(:values) { [1, 2] }
+
+    its(:count) { is_expected.to be_within(0.000001).of(2) }
+    its(:sum) { is_expected.to be_within(0.000001).of(3) }
+    its(:avg) { is_expected.to be_within(0.000001).of(1.5) }
+    its(:min) { is_expected.to be_within(0.000001).of(1) }
+    its(:max) { is_expected.to be_within(0.000001).of(2) }
+
+    it 'has proper quantiles' do
+      expect(subject.quantile(0.00)).to be_within(0.000001).of(1.0)
+      expect(subject.quantile(0.25)).to be_within(0.000001).of(1.25)
+      expect(subject.quantile(0.50)).to be_within(0.000001).of(1.5)
+      expect(subject.quantile(0.90)).to be_within(0.000001).of(1.9)
+      expect(subject.quantile(0.99)).to be_within(0.000001).of(1.99)
+    end
+  end
+end

data/spec/ddtelemetry/stopwatch_spec.rb

@@ -9,8 +9,6 @@ describe DDTelemetry::Stopwatch do
     expect(stopwatch.duration).to eq(0.0)
   end
 
-  # TODO: if running, raise error when asking for #duration
-
   it 'records correct duration after start+stop' do
     Timecop.freeze(Time.local(2008, 9, 1, 10, 5, 0))
     stopwatch.start
@@ -38,12 +36,20 @@ describe DDTelemetry::Stopwatch do
   end
 
   it 'errors when stopping when not started' do
-    expect { stopwatch.stop }.to raise_error(DDTelemetry::Stopwatch::NotRunningError)
+    expect { stopwatch.stop }
+      .to raise_error(
+        DDTelemetry::Stopwatch::NotRunningError,
+        'Cannot stop, because stopwatch is not running',
+      )
   end
 
   it 'errors when starting when already started' do
     stopwatch.start
-    expect { stopwatch.start }.to raise_error(DDTelemetry::Stopwatch::AlreadyRunningError)
+    expect { stopwatch.start }
+      .to raise_error(
+        DDTelemetry::Stopwatch::AlreadyRunningError,
+        'Cannot start, because stopwatch is already running',
+      )
   end
 
   it 'reports running status' do
@@ -60,4 +66,13 @@ describe DDTelemetry::Stopwatch do
     expect(stopwatch).not_to be_running
     expect(stopwatch).to be_stopped
   end
+
+  it 'errors when getting duration while running' do
+    stopwatch.start
+    expect { stopwatch.duration }
+      .to raise_error(
+        DDTelemetry::Stopwatch::StillRunningError,
+        'Cannot get duration, because stopwatch is still running',
+      )
+  end
 end