Class: Boxcars::Observability

Inherits:
Object
  • Object
show all
Defined in:
lib/boxcars/observability.rb

Overview

Provides a central point for tracking observability events. It allows configuring a backend (or multiple backends via MultiBackend) to which events and their properties will be sent.

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.backend ⇒ Object (readonly) 



13
14
15
 
# File 'lib/boxcars/observability.rb', line 13

def backend
  Boxcars.configuration.observability_backend
end

Class Method Details

.track(event:, properties:, observation: nil) ⇒ Object

Tracks an event if a backend is configured. This method will silently ignore errors raised by the backend's track method to prevent observability issues from disrupting the main application flow.

Parameters:

  • event (String, Symbol) —

    The name of the event to track.

  • properties (Hash) —

    A hash of properties associated with the event.

  • observation (Boxcars::Observation, nil) (defaults to: nil) —

    Optional observation object to extract user context from.



24
25
26
27
28
29
30
31
32
33
34
35
36
 
# File 'lib/boxcars/observability.rb', line 24

def track(event:, properties:, observation: nil)
  return unless backend

  # Merge user context from observation if present
  final_properties = properties.dup
  final_properties = merge_user_context(final_properties, observation.user_context) if observation&.user_context?

  backend.track(event:, properties: final_properties)
rescue StandardError
  # Fail silently as requested.
  # Optionally, if Boxcars had a central logger:
  # Boxcars.logger.warn "Boxcars::Observability: Backend error during track: #{e.message} (#{e.class.name})"
end

.track_observation(observation, event: 'boxcar_observation', **additional_properties) ⇒ Object

Tracks an observation event, automatically extracting user context if present

Parameters:

  • observation (Boxcars::Observation) —

    The observation to track

  • event (String, Symbol) (defaults to: 'boxcar_observation') —

    The event name (defaults to 'boxcar_observation')

  • additional_properties (Hash) —

    Additional properties to include



42
43
44
45
46
47
48
49
50
51
52
53
 
# File 'lib/boxcars/observability.rb', line 42

def track_observation(observation, event: 'boxcar_observation', **additional_properties)
  properties = {
    observation_note: observation.note,
    observation_status: observation.status,
    timestamp: Time.now.iso8601
  }.merge(additional_properties)

  # Add all observation context (including user_context) to properties
  properties.merge!(observation.added_context) if observation.added_context

  track(event:, properties:, observation:)
end