Module: Lutaml::Model::Instrumentation

Defined in:
lib/lutaml/model/instrumentation.rb

Overview

Instrumentation module for performance monitoring and profiling

This module provides hooks for tracking serialization performance, memory usage, and operation timing. It can be enabled/disabled globally or per-operation.

Examples:

Enable instrumentation globally

Lutaml::Model::Instrumentation.enabled = true

Subscribe to events

Lutaml::Model::Instrumentation.subscribe(:serialization) do |event|
  puts "#{event[:name]} took #{event[:duration]}ms"
end

Instrument a block

Lutaml::Model::Instrumentation.instrument(:parse, model: MyClass) do
  MyClass.from_xml(xml_string)
end

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.events ⇒ Object (readonly)

Returns the value of attribute events.



26
27
28
 
# File 'lib/lutaml/model/instrumentation.rb', line 26

def events
  @events
end

.subscribers ⇒ Object (readonly)

Returns the value of attribute subscribers.



26
27
28
 
# File 'lib/lutaml/model/instrumentation.rb', line 26

def subscribers
  @subscribers
end

Class Method Details

.clear_subscribers ⇒ void

This method returns an undefined value.

Clear all subscribers



74
75
76
 
# File 'lib/lutaml/model/instrumentation.rb', line 74

def clear_subscribers
  @subscribers&.clear
end

.enabled=(value) ⇒ Boolean

Enable or disable instrumentation

Parameters:

  • value (Boolean) —

    true to enable, false to disable

Returns:

  • (Boolean) —

    the current enabled state



32
33
34
35
 
# File 'lib/lutaml/model/instrumentation.rb', line 32

def enabled=(value)
  @enabled = value
  @subscribers ||= {} if value
end

.enabled? ⇒ Boolean

Check if instrumentation is enabled

Returns:

  • (Boolean) 


40
41
42
 
# File 'lib/lutaml/model/instrumentation.rb', line 40

def enabled?
  @enabled == true
end

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

Instrument a block of code

Parameters:

  • name (Symbol) —

    the operation name

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

    additional payload data

Yields:

  • the block to instrument

Returns:

  • (Object) —

    the block’s return value



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/lutaml/model/instrumentation.rb', line 84

def instrument(name, payload = {})
  return yield unless enabled?

  start_time = monotonic_time
  start_mem = memory_usage if payload[:track_memory]

  result = yield

  end_time = monotonic_time
  end_mem = memory_usage if payload[:track_memory]

  event = {
    name: name,
    duration: ((end_time - start_time) * 1000).round(2), # ms
    payload: payload,
  }

  if payload[:track_memory]
    event[:memory_before] = start_mem
    event[:memory_after] = end_mem
    event[:memory_delta] = end_mem - start_mem if end_mem && start_mem
  end

  notify(name, event)

  result
end

.recorded_events ⇒ Array<Hash>

Get all recorded events (when recording is enabled)

Returns:

  • (Array<Hash>) —

    the recorded events



115
116
117
 
# File 'lib/lutaml/model/instrumentation.rb', line 115

def recorded_events
  @recorded_events ||= []
end

.recording? ⇒ Boolean

Check if recording is active

Returns:

  • (Boolean) 


138
139
140
 
# File 'lib/lutaml/model/instrumentation.rb', line 138

def recording?
  @recording == true
end

.reset! ⇒ void

This method returns an undefined value.

Reset all instrumentation state



145
146
147
148
149
150
 
# File 'lib/lutaml/model/instrumentation.rb', line 145

def reset!
  @enabled = false
  @subscribers = nil
  @events = nil
  @recording = false
end

.start_recording ⇒ void

This method returns an undefined value.

Start recording events



122
123
124
125
 
# File 'lib/lutaml/model/instrumentation.rb', line 122

def start_recording
  @recording = true
  @events = []
end

.stop_recording ⇒ Array<Hash>

Stop recording events

Returns:

  • (Array<Hash>) —

    the recorded events



130
131
132
133
 
# File 'lib/lutaml/model/instrumentation.rb', line 130

def stop_recording
  @recording = false
  @events || []
end

.subscribe(*event_names) {|Hash| ... } ⇒ Proc

Subscribe to instrumentation events

Parameters:

  • event_name (Symbol, Array<Symbol>) —

    the event name(s) to subscribe to

Yields:

  • (Hash) —

    the event payload

Returns:

  • (Proc) —

    the subscriber block



49
50
51
52
53
54
55
56
57
58
 
# File 'lib/lutaml/model/instrumentation.rb', line 49

def subscribe(*event_names, &block)
  return unless enabled?

  @subscribers ||= {}
  event_names.each do |name|
    @subscribers[name] ||= []
    @subscribers[name] << block
  end
  block
end

.unsubscribe(event_name, block) ⇒ void

This method returns an undefined value.

Unsubscribe from instrumentation events

Parameters:

  • event_name (Symbol) —

    the event name

  • block (Proc) —

    the subscriber block to remove



65
66
67
68
69
 
# File 'lib/lutaml/model/instrumentation.rb', line 65

def unsubscribe(event_name, block)
  return unless @subscribers

  @subscribers[event_name]&.delete(block)
end