timify 0.0.5 → 1.0.0

data/lib/timify/recording.rb

@@ -0,0 +1,375 @@
+# frozen_string_literal: true
+
+class Timify
+  # Retained samples per bucket. min, max, count, and the sums stay exact
+  # after this cap; percentiles then use the retained prefix.
+  MAX_SAMPLES = 10_000
+
+  THREAD_STATE_KEY = :__timify_thread_state__
+
+  # Pauses or resumes recording.
+  # Time spent paused is dropped: the next segment on each thread starts when
+  # the timer is turned back on. +:off+ does not erase segments already recorded.
+  #
+  # @param value [Symbol, String] +:on+ or +:off+
+  # @return [Symbol]
+  # @raise [ArgumentError] when +value+ is not +:on+ or +:off+
+  def status=(value)
+    normalized = value.respond_to?(:to_sym) ? value.to_sym : nil
+    unless %i[on off].include?(normalized)
+      raise ArgumentError, "status must be :on or :off"
+    end
+
+    synchronize do
+      if @status == :on && normalized == :off
+        @pause_started = monotonic
+      elsif @status == :off && normalized == :on
+        now = monotonic
+        @paused_monotonic += now - @pause_started if @pause_started
+        @pause_started = nil
+        @resume_at = now
+        thread_state[:last_mark] = now
+      end
+      @status = normalized
+    end
+  end
+
+  # Records the time elapsed since the previous mark on this thread.
+  # Inside {#measure}, the mark becomes a child span instead of being counted
+  # again as part of the parent's self time. The first call on a thread has no
+  # range. Later calls record the jump from the previous call site to this one.
+  # When {.enabled} is +false+, returns +0.0+ and records nothing.
+  #
+  # @param label [Object, nil] optional name. Symbols and strings with the
+  #   same text are grouped together. +nil+ and blank strings are ignored.
+  # @return [Float] self time of this segment, or +0.0+ when paused or disabled
+  def add(label = nil)
+    return 0.0 unless self.class.enabled?
+
+    location = caller_location
+    normalized = normalize_label(label)
+    time_spent, events = synchronize do
+      paused? ? [0.0, []] : record_add(location, normalized)
+    end
+    deliver(events)
+    time_spent
+  end
+
+  # Records the time spent inside +block+ and returns the block's value.
+  # Time from the previous mark up to this call is stored first, when it is
+  # longer than zero, as an unlabeled segment. The block is a span: its
+  # inclusive time is the whole block, and its self time is what nested
+  # {#measure} and {#add} calls did not take. If the block raises, the span is
+  # still recorded and the exception propagates. While paused, or when
+  # {.enabled} is +false+, the block runs and nothing is recorded.
+  #
+  # @param label [Object, nil] same rules as {#add}
+  # @yield the work to time
+  # @return [Object] the block's return value
+  # @raise [ArgumentError] when no block is given
+  def measure(label = nil)
+    raise ArgumentError, "measure requires a block" unless block_given?
+    return yield unless self.class.enabled?
+
+    location = caller_location
+    normalized = normalize_label(label)
+    opened = false
+    events = []
+    synchronize do
+      unless paused?
+        open_measure(location, normalized)
+        opened = true
+      end
+    end
+    return yield unless opened
+
+    begin
+      yield
+    ensure
+      synchronize { events = close_measure }
+      deliver(events)
+    end
+  end
+
+  # Registers a callback invoked when a segment is at least +seconds+ long.
+  # {#add} compares the segment. {#measure} compares the block's inclusive
+  # time. Callbacks run after the timer has recorded the segment, and several
+  # callbacks can be registered.
+  #
+  # @param seconds [Numeric]
+  # @yield [event]
+  # @yieldparam event [Timify::Event]
+  # @return [Timify] self
+  # @raise [ArgumentError] when no block is given or +seconds+ is negative
+  def on_slow(seconds, &block)
+    raise ArgumentError, "on_slow requires a block" unless block
+
+    threshold = Float(seconds)
+    raise ArgumentError, "threshold must be >= 0" if threshold.negative?
+
+    synchronize { @slow_handlers << [threshold, block] }
+    self
+  end
+
+  # Registers a callback invoked when a child span's inclusive time is at least
+  # +ratio+ of the parent's elapsed time so far. Fires for labeled {#measure}
+  # and {#add} children, not for root spans or unlabeled gap spans. Several
+  # callbacks can be registered. They run after the segment is recorded,
+  # outside the timer mutex.
+  #
+  # @param ratio [Numeric] share from +0+ to +1+ inclusive
+  # @yield [event]
+  # @yieldparam event [Timify::Event] includes +share+ and +parent_label+
+  # @return [Timify] self
+  # @raise [ArgumentError] when no block is given or +ratio+ is outside +0..1+
+  def on_share(ratio, &block)
+    raise ArgumentError, "on_share requires a block" unless block
+
+    value = Float(ratio)
+    unless value >= 0.0 && value <= 1.0
+      raise ArgumentError, "ratio must be between 0 and 1"
+    end
+
+    synchronize { @share_handlers << [value, block] }
+    self
+  end
+
+  # Clears recorded segments and starts the clock again.
+  # Keeps {#name}, {#show}, {#min_time_to_show}, {#output}, {#on_slow}, and
+  # {#on_share} callbacks. The timer is left running even if it was paused.
+  # Other threads drop their old cursor on the next mark.
+  #
+  # @return [Timify] self
+  def reset
+    synchronize do
+      @generation += 1
+      @status = :on
+      @locations = {}
+      @labels = {}
+      @ranges = {}
+      @roots = []
+      @total = 0.0
+      @max_time_spent = 0.0
+      @initial_time = Time.now
+      @finished_time = @initial_time
+      @paused_monotonic = 0.0
+      @pause_started = nil
+      @resume_at = nil
+      now = monotonic
+      @origin_mark = now
+      @last_record_mark = now
+      thread_table[object_id] = {
+        generation: @generation,
+        last_mark: now,
+        stack: [],
+        location_prev: nil
+      }
+    end
+    self
+  end
+
+  private
+
+  def synchronize(&block)
+    @mutex.synchronize(&block)
+  end
+
+  def paused?
+    @status == :off
+  end
+
+  def monotonic
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def thread_table
+    Thread.current[THREAD_STATE_KEY] ||= {}
+  end
+
+  def thread_state
+    state = thread_table[object_id]
+    if state.nil? || state[:generation] != @generation
+      state = {
+        generation: @generation,
+        last_mark: monotonic,
+        stack: [],
+        location_prev: nil
+      }
+      thread_table[object_id] = state
+    end
+    state[:last_mark] = @resume_at if @resume_at && state[:last_mark] < @resume_at
+    state
+  end
+
+  def normalize_label(label)
+    return nil if label.nil?
+
+    text = label.to_s.strip
+    text.empty? ? nil : text
+  end
+
+  def record_add(location, label)
+    state = thread_state
+    now = monotonic
+    time_spent = (now - state[:last_mark]).to_f
+    state[:last_mark] = now
+    record_segment(location, label, time_spent, inclusive: time_spent, range: true, state: state)
+    parent = state[:stack].last
+    attach_span(state, Span.new(label: label, location: location).tap { |span|
+      span.inclusive = time_spent
+      span.exclusive = time_spent
+    })
+    events = slow_events(label, location, time_spent, time_spent)
+    events.concat(share_events(label, location, time_spent, time_spent, parent, now))
+    [time_spent, events]
+  end
+
+  def open_measure(location, label)
+    state = thread_state
+    now = monotonic
+    gap = (now - state[:last_mark]).to_f
+    if gap.positive?
+      state[:last_mark] = now
+      record_segment(location, nil, gap, inclusive: gap, range: true, state: state)
+      attach_span(state, Span.new(label: nil, location: location).tap { |span|
+        span.inclusive = gap
+        span.exclusive = gap
+      })
+    end
+    state[:stack] << Span.new(label: label, location: location, started_mark: now)
+    state[:last_mark] = now
+  end
+
+  def close_measure
+    state = thread_state
+    span = state[:stack].pop
+    finished = monotonic
+    inclusive = (finished - span.started_mark).to_f
+    exclusive = inclusive - span.children.sum(&:inclusive)
+    exclusive = 0.0 if exclusive.negative?
+    span.inclusive = inclusive
+    span.exclusive = exclusive
+    state[:last_mark] = finished
+    record_segment(span.location, span.label, exclusive, inclusive: inclusive, range: false, state: state)
+    state[:location_prev] = span.location
+    parent = state[:stack].last
+    attach_span(state, span)
+    events = slow_events(span.label, span.location, exclusive, inclusive)
+    events.concat(share_events(span.label, span.location, exclusive, inclusive, parent, finished))
+    events
+  end
+
+  def attach_span(state, span)
+    if (parent = state[:stack].last)
+      parent.children << span
+    else
+      @roots << span
+    end
+  end
+
+  def record_segment(location, label, exclusive, inclusive:, range:, state:)
+    @total += exclusive
+    @finished_time = Time.now
+    @last_record_mark = state[:last_mark]
+    new_max = exclusive > @max_time_spent
+    @max_time_spent = exclusive if new_max
+
+    update_bucket(@locations, location, exclusive, inclusive)
+    update_bucket(@labels, label, exclusive, inclusive) if label
+    if range && state[:location_prev]
+      update_bucket(@ranges, "#{state[:location_prev]} - #{location}", exclusive, inclusive)
+    end
+    state[:location_prev] = location if range
+
+    return if exclusive < @min_time_to_show
+
+    emit(segment_message(label, new_max, location, location_percent(location), exclusive))
+  end
+
+  def update_bucket(buckets, key, exclusive, inclusive)
+    bucket = buckets[key] ||= empty_bucket
+    bucket[:secs] += exclusive
+    bucket[:inclusive] += inclusive
+    bucket[:count] += 1
+    bucket[:min] = exclusive if bucket[:min].nil? || exclusive < bucket[:min]
+    bucket[:max] = exclusive if bucket[:max].nil? || exclusive > bucket[:max]
+    if bucket[:samples].length < MAX_SAMPLES
+      bucket[:samples] << exclusive
+    else
+      bucket[:samples_truncated] = true
+    end
+    bucket
+  end
+
+  def empty_bucket
+    {
+      secs: 0.0,
+      inclusive: 0.0,
+      count: 0,
+      min: nil,
+      max: nil,
+      samples: [],
+      samples_truncated: false
+    }
+  end
+
+  def location_percent(location)
+    return 0 if @total.zero?
+
+    ((@locations[location][:secs] / @total) * 100).round
+  end
+
+  def slow_events(label, location, secs, inclusive)
+    @slow_handlers.filter_map do |threshold, handler|
+      next if inclusive < threshold
+
+      [handler, Event.new(name: @name, label: label, location: location, secs: secs, inclusive: inclusive)]
+    end
+  end
+
+  def share_events(label, location, secs, inclusive, parent, now)
+    return [] if parent.nil? || label.nil?
+
+    parent_elapsed = (now - parent.started_mark).to_f
+    return [] if parent_elapsed <= 0.0
+
+    share = inclusive / parent_elapsed
+    @share_handlers.filter_map do |ratio, handler|
+      next if share < ratio
+
+      [
+        handler,
+        Event.new(
+          name: @name,
+          label: label,
+          location: location,
+          secs: secs,
+          inclusive: inclusive,
+          share: share,
+          parent_label: parent.label
+        )
+      ]
+    end
+  end
+
+  def deliver(events)
+    events.each { |handler, event| handler.call(event) }
+  end
+
+  def segment_message(label, new_max, location, percent, time_spent)
+    label_text = label ? "<#{label}>" : ""
+    max_text = new_max ? "(New Max)" : ""
+    "<#{@name}>#{label_text}#{max_text}: #{location} (#{percent}%): " \
+      "#{format_secs(@total)}; #{format_secs(time_spent)}"
+  end
+
+  def emit(message)
+    return unless @show
+
+    if @output.respond_to?(:info) && !@output.respond_to?(:puts)
+      @output.info(message)
+    else
+      @output.puts(message)
+    end
+  end
+end

data/lib/timify/registry.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+class Timify
+  REGISTRY_MUTEX = Mutex.new
+
+  # Returns the timer registered under +name+, creating it on first use.
+  # Registered timers start with +show: false+ so fetching one does not print.
+  #
+  # @param name [Object]
+  # @return [Timify]
+  def self.[](name)
+    REGISTRY_MUTEX.synchronize do
+      registry[name] ||= new(name, show: false)
+    end
+  end
+
+  # Drops every timer created through {.[]}.
+  #
+  # @return [void]
+  def self.clear!
+    REGISTRY_MUTEX.synchronize { @registry = {} }
+  end
+
+  class << self
+    private
+
+    def registry
+      @registry ||= {}
+    end
+  end
+end

data/lib/timify/report.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+class Timify
+  # Returns the report for every segment recorded so far.
+  # Pausing the timer does not hide this report. When {#show} is true, the
+  # printable summary is also written to {#output}.
+  #
+  # +locations+, +labels+, and +ranges+ are ordered by self time, slowest
+  # first. Each entry contains:
+  # - +secs+ [Float] accumulated self time
+  # - +inclusive+ [Float] accumulated inclusive time
+  # - +percent+ [Integer] share of {#total}, rounded to the nearest percent
+  # - +count+ [Integer] number of segments
+  # - +min+ [Float] shortest self time
+  # - +max+ [Float] longest self time
+  # - +avg+ [Float] +secs / count+
+  # - +p50+, +p95+, +p99+ [Float] nearest-rank percentiles of self time
+  # - +samples_truncated+ [Boolean] present when the percentile sample was capped
+  #
+  # +tree+ is the chronological list of top-level spans. Each node has
+  # +label+, +location+, +secs+, +inclusive+, and +children+.
+  # +grouped_tree+ merges sibling nodes with the same label recursively:
+  # +secs+ and +inclusive+ are summed, +count+ is how many spans were merged,
+  # and +children+ are grouped the same way. Order of first appearance is
+  # preserved. +wall_time+ is monotonic time from the start to the latest mark,
+  # minus pauses.
+  #
+  # @param json [Boolean] when true, return the same report as a JSON string
+  # @param group [Boolean] when true, print a +Grouped spans:+ section after
+  #   the chronological Spans section. +grouped_tree+ is always included in
+  #   the hash either way.
+  # @return [Hash, String]
+  def totals(json: false, group: false)
+    report = synchronize { build_report(group: group) }
+    emit(report[:message])
+
+    if json
+      require "json"
+      report.to_json
+    else
+      report
+    end
+  end
+
+  private
+
+  def caller_location
+    format_location(caller_locations(2, 1).first)
+  end
+
+  def format_location(loc)
+    path = relative_path(loc.absolute_path || loc.path)
+    method = loc.base_label
+    suffix = method.nil? || method.empty? ? "" : " in #{method}"
+    "#{path}:#{loc.lineno}#{suffix}"
+  end
+
+  def relative_path(path)
+    return path if path.nil? || path.empty?
+
+    expanded = File.expand_path(path)
+    prefix = "#{Dir.pwd}/"
+    expanded.start_with?(prefix) ? expanded.delete_prefix(prefix) : expanded
+  end
+
+  def build_report(group: false)
+    wall = @last_record_mark - @origin_mark - @paused_monotonic
+    wall = 0.0 if wall.negative?
+    tree = @roots.map(&:to_h)
+    report = {
+      name: @name,
+      total_time: @total.to_f,
+      wall_time: wall.to_f,
+      started: @initial_time,
+      finished: @finished_time,
+      tree: tree,
+      grouped_tree: group_tree(tree),
+      locations: report_buckets(@locations),
+      labels: report_buckets(@labels),
+      ranges: report_buckets(@ranges)
+    }
+    report[:message] = summary_message(report, group: group)
+    report
+  end
+
+  def group_tree(nodes)
+    order = []
+    buckets = {}
+    nodes.each do |node|
+      key = node[:label]
+      unless buckets.key?(key)
+        order << key
+        buckets[key] = []
+      end
+      buckets[key] << node
+    end
+    order.map do |key|
+      group = buckets[key]
+      first = group.first
+      {
+        label: first[:label],
+        location: first[:location],
+        secs: group.sum { |node| node[:secs] },
+        inclusive: group.sum { |node| node[:inclusive] },
+        count: group.size,
+        children: group_tree(group.flat_map { |node| node[:children] })
+      }
+    end
+  end
+
+  def report_buckets(buckets)
+    ordered = buckets.sort_by { |key, bucket| [-bucket[:secs], key.to_s] }
+    ordered.each_with_object({}) do |(key, bucket), report|
+      count = bucket[:count]
+      secs = bucket[:secs]
+      samples = bucket[:samples].sort
+      entry = {
+        secs: secs,
+        inclusive: bucket[:inclusive],
+        percent: @total.zero? ? 0 : (secs * 100 / @total.to_f).round,
+        count: count,
+        min: bucket[:min] || 0.0,
+        max: bucket[:max] || 0.0,
+        avg: count.zero? ? 0.0 : secs / count,
+        p50: percentile(samples, 50),
+        p95: percentile(samples, 95),
+        p99: percentile(samples, 99)
+      }
+      entry[:samples_truncated] = true if bucket[:samples_truncated]
+      report[key] = entry
+    end
+  end
+
+  # Nearest-rank percentile. +samples+ must already be sorted.
+  def percentile(samples, percent)
+    return 0.0 if samples.empty?
+
+    rank = (percent / 100.0 * samples.length).ceil
+    rank = 1 if rank < 1
+    samples[rank - 1]
+  end
+
+  def summary_message(report, group: false)
+    message = "\n\nTotal time <#{@name}>:#{format_secs(report[:total_time])} wall #{format_secs(report[:wall_time])}"
+    unless report[:tree].empty?
+      message += "\nSpans:\n"
+      message += tree_text(report[:tree])
+      if group && !report[:grouped_tree].empty?
+        message += "Grouped spans:\n"
+        message += tree_text(report[:grouped_tree])
+      end
+      message += "Total time by location:\n"
+    else
+      message += "\nTotal time by location:\n"
+    end
+    message += bucket_text(report[:locations])
+    unless report[:labels].empty?
+      message += "\nTotal time by label:\n"
+      message += bucket_text(report[:labels])
+    end
+    unless report[:ranges].empty?
+      message += "\nTotal time by range:\n"
+      message += bucket_text(report[:ranges])
+    end
+    "#{message}\n\n"
+  end
+
+  def tree_text(nodes, depth = 0)
+    nodes.map { |node|
+      label = node[:label] || "(gap)"
+      count = node.key?(:count) ? " ##{node[:count]}" : ""
+      line = "\t#{'  ' * depth}#{label} inclusive #{format_secs(node[:inclusive])} self #{format_secs(node[:secs])}#{count}\n"
+      line + tree_text(node[:children], depth + 1)
+    }.join
+  end
+
+  def bucket_text(buckets)
+    buckets.map { |key, data|
+      inclusive = ""
+      if (data[:inclusive] - data[:secs]).abs > 0.000_001
+        inclusive = " inclusive #{format_secs(data[:inclusive])}"
+      end
+      "\t#{key}: #{format_secs(data[:secs])} (#{data[:percent]}%) ##{data[:count]} " \
+        "min #{format_secs(data[:min])} max #{format_secs(data[:max])} avg #{format_secs(data[:avg])} " \
+        "p95 #{format_secs(data[:p95])}#{inclusive}\n"
+    }.join
+  end
+
+  def format_secs(value)
+    value.round(2)
+  end
+end

data/lib/timify/span.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+class Timify
+  # One timed block or mark in the tree returned by {Timify#totals}.
+  class Span
+    attr_accessor :label, :location, :inclusive, :exclusive, :children, :started_mark
+
+    def initialize(label:, location:, started_mark: nil)
+      @label = label
+      @location = location
+      @started_mark = started_mark
+      @inclusive = 0.0
+      @exclusive = 0.0
+      @children = []
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        label: label,
+        location: location,
+        secs: exclusive,
+        inclusive: inclusive,
+        children: children.map(&:to_h)
+      }
+    end
+  end
+
+  # A segment that crossed an {Timify#on_slow} or {Timify#on_share} threshold.
+  class Event
+    # @return [Object]
+    attr_reader :name
+
+    # @return [String, nil]
+    attr_reader :label
+
+    # @return [String]
+    attr_reader :location
+
+    # @return [Float] self time of the segment
+    attr_reader :secs
+
+    # @return [Float] inclusive time of the segment
+    attr_reader :inclusive
+
+    # @return [Float, nil] child inclusive / parent elapsed so far; set for
+    #   {Timify#on_share} events, +nil+ for {Timify#on_slow}
+    attr_reader :share
+
+    # @return [String, nil] label of the parent span; set for {Timify#on_share}
+    #   events, +nil+ for {Timify#on_slow}
+    attr_reader :parent_label
+
+    # @param name [Object]
+    # @param label [String, nil]
+    # @param location [String]
+    # @param secs [Float]
+    # @param inclusive [Float]
+    # @param share [Float, nil]
+    # @param parent_label [String, nil]
+    def initialize(name:, label:, location:, secs:, inclusive:, share: nil, parent_label: nil)
+      @name = name
+      @label = label
+      @location = location
+      @secs = secs
+      @inclusive = inclusive
+      @share = share
+      @parent_label = parent_label
+    end
+  end
+end

data/lib/timify/trace.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Timify
+  # Result of {.trace}: the block's return value and the timer used to measure it.
+  class Trace
+    # @return [Object] the block's return value
+    attr_reader :value
+
+    # @return [Timify] the timer created for the block
+    attr_reader :timer
+
+    # @param value [Object]
+    # @param timer [Timify]
+    def initialize(value:, timer:)
+      @value = value
+      @timer = timer
+    end
+
+    # Delegates to {Timify#totals} on {#timer}.
+    #
+    # @param options [Hash] keyword arguments accepted by {Timify#totals}
+    # @return [Hash, String]
+    def totals(**options)
+      @timer.totals(**options)
+    end
+  end
+end

data/lib/timify/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Timify
+  VERSION = "1.0.0"
+end