Clepsydra

Clepsydra is an instrumentation tool allowing instrumenting events. You can subscribe to events to receive instrument notifications once done.

• Clepsydra provides correct execution time information for multiple subscribers of the same event compared to ActiveSupport::Notifications:

  5.times do
    ActiveSupport::Notifications.subscribe('foo') do |_name, start, finish, _id, _payload|
      puts "#{start.to_i} #{finish.to_i} #{finish - start}"
  
      sleep 1
    end
  end
  
  ActiveSupport::Notifications.instrument('foo') {}
  
  # 1642778642 1642778642 8.0e-06
  # 1642778642 1642778643 1.003928
  # 1642778642 1642778644 2.008781
  # 1642778642 1642778645 3.014062
  # 1642778642 1642778646 4.016004
  
  5.times do
    Clepsydra.subscribe('foo') do |_event_data, start, finish, _payload|
      puts "#{start.to_i} #{finish.to_i} #{finish - start}"
  
      sleep 1
    end
  end
  
  Clepsydra.instrument('foo') {}
  
  # 1642778782 1642778782 1.7e-05
  # 1642778782 1642778782 1.7e-05
  # 1642778782 1642778782 1.7e-05
  # 1642778782 1642778782 1.7e-05
  # 1642778782 1642778782 1.7e-05

• Clepsydra offers APIs to measure non-blocking events correctly.

Add this line to your Gemfile and bundle install:

gem 'clepsydra', '~> 0.1.0'

Clepsydra requires Ruby >= 2.5.0.

Read the benchmark document.

• Clepsyndra.instrument(event_name[, payload])

Instrumenters provide a way to instrument an event. These first execute the block and notify all the subscribers even if the instrumented block raises an exception. In such a case, the notification contains the exception information in the payload.

Clepsydra.instrument('foo', { bar: 'baz' }) do
  FirstTask.perform
  SecondTask.perform
end

• Clepsyndra.subscribe(event_name) { |*args| } => Clepsyndra::Subscriber
• Clepsyndra.monotonic_subscribe(event_name) { |*args| } => Clepsyndra::Subscriber

Subscribers consume instrumented events. You can register multiple subscribers for the same event.

Clepsydra.subscribe('foo') do |event_data, start, finish, payload|
  # This is a blocking call avoid long-running tasks
  #
  # event_data            [Hash] the event data
  #   * :event_name       [String] the event name
  #   * :event_id         [String] unique ID of the event
  #   * :notifier_id      [String] unique ID of the notifier
  #   * :instrumenter_id  [String] unique ID of the instrumenter who fired the event
  #   * :subscriber_id    [String] unique ID of the current subscriber
  # start                 [Time] instrumented block execution start time
  # finish                [Time] instumented block execution end time
  # payload               [Hash] the payload
end

In case of an error in the instrumented block, the payload additionally has:

• exception: The exception object
• execption_message: The result of calling execption.inspect

Note that, the time is a wall-clock time. You can use monotonic_subscribe for better accuracy as it uses monotonic time.

• Clepsydra.unsubscribe(event_name_or_subscriber)

You can unsubscribe either all the subscribers to a particular event or a specific subscriber.

Clepsydra.subscribe('foo') {}
Clepsydra.subscribe('foo') {}
Clepsydra.monotonic_subscribe('foo') {}

# Unsubscribe all
Clepsydra.unsubscribe('foo')

first = Clepsydra.subscribe('foo') {}
second = Clepsydra.monotonic_subscribe('foo') {}

# Unsubscribe one
Clepsydra.unsubscribe(second)

• Clepsydra.start(event_name) => String
• Clepsydra.finish(event_name, event_id[, payload])

You can explicitly mark the start of an event and then fire the finish that notifies all the subscribers. You must fire both start and finish in the same thread context. It allows to instrument multiple events running in a block explicitly when it is not desired to instrument the entire block or each event entirely.

tasks.each do |task|
  Clepsydra.instrument('foo') do
    task.on_complete { |data| }
    task.submit # Non-blocking
  end
end

The above does not provide accurate instrumentation as it exits immediately after submitting the tasks.

tasks.each do |task|
  event_id = Clepsydra.start('foo')
  task.on_complete { |data| Clepsydra.finish('foo', event_id, data) }
  task.submit # Non-blocking
end

Read the contribution guide.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Clepsydra's codebases, issue trackers, chat rooms and mailing lists is expected to follow the Code of Conduct.