Module: ClickhouseRuby::Instrumentation

Defined in:
lib/clickhouse_ruby/instrumentation.rb

Overview

Instrumentation module for observability and monitoring

Provides ActiveSupport::Notifications integration when available, with graceful fallback for non-Rails applications.

Examples:

Subscribe to events (with ActiveSupport)

ActiveSupport::Notifications.subscribe(/clickhouse_ruby/) do |name, start, finish, id, payload|
  duration = finish - start
  Rails.logger.info "#{name} took #{duration}s"
end

Subscribe to specific events

ActiveSupport::Notifications.subscribe('clickhouse_ruby.query.complete') do |*args|
  event = ActiveSupport::Notifications::Event.new(*args)
  puts "Query: #{event.payload[:sql]} took #{event.duration}ms"
end

Defined Under Namespace

Modules: Helpers

Constant Summary collapse

EVENTS =

Event names for instrumentation

{
  query_start: "clickhouse_ruby.query.start",
  query_complete: "clickhouse_ruby.query.complete",
  query_error: "clickhouse_ruby.query.error",
  insert_start: "clickhouse_ruby.insert.start",
  insert_complete: "clickhouse_ruby.insert.complete",
  pool_checkout: "clickhouse_ruby.pool.checkout",
  pool_checkin: "clickhouse_ruby.pool.checkin",
  pool_timeout: "clickhouse_ruby.pool.timeout",
}.freeze

Class Method Summary collapse

Class Method Details

.available? ⇒ Boolean

Check if ActiveSupport::Notifications is available

Returns:

  • (Boolean) —

    true if ActiveSupport::Notifications is available



38
39
40
 
# File 'lib/clickhouse_ruby/instrumentation.rb', line 38

def available?
  defined?(ActiveSupport::Notifications)
end

.duration_ms(started_at) ⇒ Float

Calculate duration in milliseconds from a start time

Parameters:

  • started_at (Float) —

    monotonic start time

Returns:

  • (Float) —

    duration in milliseconds



90
91
92
 
# File 'lib/clickhouse_ruby/instrumentation.rb', line 90

def duration_ms(started_at)
  (monotonic_time - started_at) * 1000
end

.instrument(event_name, payload = {}) { ... } ⇒ Object

Instrument a block of code with timing and event notification

When ActiveSupport::Notifications is available, publishes an event with the given name and payload. Otherwise, still tracks timing for logging purposes.

Examples:

Instrumentation.instrument('clickhouse_ruby.query.complete', sql: 'SELECT 1') do
  execute_query
end

Parameters:

  • event_name (String) —

    the event name to publish

  • payload (Hash) (defaults to: {}) —

    additional payload data

Yields:

  • the block to instrument

Returns:

  • (Object) —

    the result of the block



57
58
59
60
61
62
63
 
# File 'lib/clickhouse_ruby/instrumentation.rb', line 57

def instrument(event_name, payload = {})
  if available?
    ActiveSupport::Notifications.instrument(event_name, payload) { yield }
  else
    instrument_without_as(event_name, payload) { yield }
  end
end

.monotonic_time ⇒ Float

Returns a monotonic timestamp for duration calculation

Uses Process.clock_gettime for accurate timing that isn’t affected by system clock changes.

Returns:

  • (Float) —

    monotonic timestamp in seconds



82
83
84
 
# File 'lib/clickhouse_ruby/instrumentation.rb', line 82

def monotonic_time
  Process.clock_gettime(Process::CLOCK_MONOTONIC)
end

.publish(event_name, payload = {}) ⇒ void

This method returns an undefined value.

Publish an event without a block (for start/error events)

Parameters:

  • event_name (String) —

    the event name to publish

  • payload (Hash) (defaults to: {}) —

    the event payload



70
71
72
73
74
 
# File 'lib/clickhouse_ruby/instrumentation.rb', line 70

def publish(event_name, payload = {})
  return unless available?

  ActiveSupport::Notifications.publish(event_name, payload)
end