Class: RosettAi::Telemetry::Reporter

Inherits:
Object
  • Object
show all
Defined in:
lib/rosett_ai/telemetry/reporter.rb

Overview

Singleton reporter that writes structured telemetry events.

Events are written as JSON Lines to stderr (default) or a file specified by +RAI_TELEMETRY_FILE+. Providers can be registered to receive event notifications.

Author:

  • hugo

  • claude

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Reporter

Returns a new instance of Reporter.



41
42
43
44
45
46
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 41

def initialize
  @providers = []
  @mutex = Mutex.new
  @correlation_id = SecureRandom.uuid
  @writer = resolve_writer
end

Instance Attribute Details

#correlation_id ⇒ String (readonly)

Returns correlation ID for this session.

Returns:

  • (String) —

    correlation ID for this session



95
96
97
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 95

def correlation_id
  @correlation_id
end

Class Method Details

.enabled? ⇒ Boolean

Returns telemetry enabled?.

Returns:

  • (Boolean) —

    telemetry enabled?



37
38
39
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 37

def self.enabled?
  RosettAi::Telemetry.enabled?
end

.instance ⇒ Reporter

Returns singleton instance.

Returns:



23
24
25
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 23

def self.instance
  @mutex.synchronize { @instance ||= new }
end

.reset!

This method returns an undefined value.

Reset singleton. Intended for test isolation.



29
30
31
32
33
34
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 29

def self.reset!
  @mutex.synchronize do
    @instance&.close
    @instance = nil
  end
end

Instance Method Details

#close

This method returns an undefined value.

Close any open file handles.



99
100
101
102
103
104
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 99

def close
  @mutex.synchronize do
    @writer&.close
    @writer = nil
  end
end

#command_end(command:, duration_ms:, status:, **data)

This method returns an undefined value.

Emit a command_end event with timing.

Parameters:

  • command (String) —

    command name

  • duration_ms (Float) —

    execution time in milliseconds

  • status (String) —

    outcome ('success' or 'error')

  • data (Hash) —

    additional data



81
82
83
84
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 81

def command_end(command:, duration_ms:, status:, **data)
  write_event(level: :info, event: :command_end, command: command,
              duration_ms: duration_ms, status: status, **data)
end

#command_start(command:, **data)

This method returns an undefined value.

Emit a command_start event.

Parameters:

  • command (String) —

    command name

  • data (Hash) —

    additional data



70
71
72
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 70

def command_start(command:, **data)
  write_event(level: :info, event: :command_start, command: command, **data)
end

#register_provider(provider)

This method returns an undefined value.

Register a telemetry provider.

Parameters:

  • provider (#report) —

    object implementing the Provider interface



90
91
92
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 90

def register_provider(provider)
  @mutex.synchronize { @providers << provider }
end

#write_event(level:, event:, **data)

This method returns an undefined value.

Write a telemetry event.

Parameters:

  • level (Symbol, String) —

    event severity (:debug, :info, :warn, :error)

  • event (Symbol, String) —

    event name (e.g. :command_start)

  • data (Hash) —

    additional event data



54
55
56
57
58
59
60
61
62
63
 
# File 'lib/rosett_ai/telemetry/reporter.rb', line 54

def write_event(level:, event:, **data)
  return unless self.class.enabled?
  return unless RosettAi::Telemetry.level_enabled?(level)

  event_hash = build_event(level: level, event: event, **data).freeze
  @mutex.synchronize do
    safe_write(event_hash)
    @providers.each { |provider| provider.report(event_hash) }
  end
end