Class: Conrad::Collector

Inherits:
Object
  • Object
show all
Defined in:
lib/conrad/collector.rb

Overview

Used to collect a batch of events and send them using the configured emitter. This is especially useful for event recording done as part of a request/response cycle. Events can be collected here then sent at the end of the request cycle.

Configuration is set via the class level and individual instances are spawned that use this configuration. The exception to that is the ‘event_metadata` which should be per collector using: `Conrad::Collector.current.event_metadata = { whatever: ’you want’ }‘

A single instance can also be created. By default it will use any values configured for the class, but accepts override as keyword arguments.

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(processors: self.class.default_processors, formatter: self.class.default_formatter, emitter: self.class.default_emitter, emit_as_batch: self.class.default_emit_as_batch, logger: self.class.default_logger) ⇒ Collector

Returns a new instance of Collector.

Parameters:

  • processors (Array<#call>) (defaults to: self.class.default_processors) —

    set of processors to run. Defaults to processors as configured for the class.

  • formatter (#call) (defaults to: self.class.default_formatter) —

    Formatter to use. Defaults to formatter as configured for the class.

  • emitter (#call) (defaults to: self.class.default_emitter) —

    emitter to send events. Defaults to emitter as configured for the class.

  • emit_as_batch (Boolean) (defaults to: self.class.default_emit_as_batch) —

    indicates how to send events. Defaults to value configured for class.



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/conrad/collector.rb', line 97

def initialize(
  processors: self.class.default_processors,
  formatter: self.class.default_formatter,
  emitter: self.class.default_emitter,
  emit_as_batch: self.class.default_emit_as_batch,
  logger: self.class.default_logger
)
  @events = []
  @event_metadata = {}
  @processors = processors
  @processor_stack = Conrad::ProcessorStack.new(processors)
  @formatter = formatter
  @emitter = emitter
  @emit_as_batch = emit_as_batch
  @logger = logger
end

Class Attribute Details

.default_emit_as_batch ⇒ Object

Boolean indicating if the events collected should be emitted as a batch and sent as an Array to to the configured emitter or if they should instead be sent one-by-one. Defaults to false.



38
39
40
 
# File 'lib/conrad/collector.rb', line 38

def default_emit_as_batch
  @default_emit_as_batch
end

.default_emitter ⇒ Object

Returns the configured emitter. Defaults to Conrad::Emitters::Stdout.

Returns:

  • the configured emitter. Defaults to Conrad::Emitters::Stdout



56
57
58
 
# File 'lib/conrad/collector.rb', line 56

def default_emitter
  @default_emitter ||= Conrad::Emitters::Stdout.new
end

.default_formatter ⇒ Object

Returns the configured formatter. Defaults to Conrad::Formatters::Json.

Returns:

  • the configured formatter. Defaults to Conrad::Formatters::Json



51
52
53
 
# File 'lib/conrad/collector.rb', line 51

def default_formatter
  @default_formatter ||= Conrad::Formatters::JSON.new
end

.default_logger ⇒ Object

Allows assigning a default logger to use for logging out of the gem. Should respond to #debug, #info, #warn, #error, and #fatal.



42
43
44
 
# File 'lib/conrad/collector.rb', line 42

def default_logger
  @default_logger
end

.default_processors ⇒ Array<#call>

Returns:

  • (Array<#call>) 


61
62
63
 
# File 'lib/conrad/collector.rb', line 61

def default_processors
  @default_processors ||= []
end

Instance Attribute Details

#emit_as_batch ⇒ Object Also known as: emit_as_batch?

Boolean indicating if events should be sent as a batch or individually by

default for each Collector instance



83
84
85
 
# File 'lib/conrad/collector.rb', line 83

def emit_as_batch
  @emit_as_batch
end

#emitter ⇒ Object

Emitter used to send out events



79
80
81
 
# File 'lib/conrad/collector.rb', line 79

def emitter
  @emitter
end

#event_metadata ⇒ Object

Used to setup metadata that will be added to every event in the collection



67
68
69
 
# File 'lib/conrad/collector.rb', line 67

def event_metadata
  @event_metadata
end

#events ⇒ Object (readonly)

The events stored in the collector



70
71
72
 
# File 'lib/conrad/collector.rb', line 70

def events
  @events
end

#formatter ⇒ Object

Formatter used to generate sendable format for an Event



76
77
78
 
# File 'lib/conrad/collector.rb', line 76

def formatter
  @formatter
end

#logger ⇒ Object

Logger object used for sending log events



87
88
89
 
# File 'lib/conrad/collector.rb', line 87

def logger
  @logger
end

#processors ⇒ Object

ProcessorStack used on each event added



73
74
75
 
# File 'lib/conrad/collector.rb', line 73

def processors
  @processors
end

Class Method Details

.current ⇒ Conrad::Collector

Returns the collector for a given Thread that is currently active.

Returns:



46
47
48
 
# File 'lib/conrad/collector.rb', line 46

def current
  Thread.current[:conrad_collector] ||= new
end

Instance Method Details

#add_event(event) ⇒ Object

Adds an event to the Collector to be audited at a later time. The current collector’s event_metadata is added to the event, it is processed, then it is formatter before being added to the set of events. If ‘:halt_conrad_processing` is thrown during the event processing, then the event will not be added to the collection.

Parameters:

  • event (Hash)

Raises:

  • (ForbiddenKey) —

    when a key is neither a Symbol nor a String



123
124
125
126
127
128
129
130
131
 
# File 'lib/conrad/collector.rb', line 123

def add_event(event)
  processed_event = processor_stack.call(event.merge(event_metadata))

  return unless processed_event

  validate_event_keys(processed_event)

  events << formatter.call(processed_event)
end

#add_metadata(new_metadata) ⇒ Object

Adds the given hash of data to the already existing event metadata

Parameters:

  • new_metadata (Hash)

Returns:

  • nothing



164
165
166
 
# File 'lib/conrad/collector.rb', line 164

def add_metadata(new_metadata)
  event_metadata.merge!(new_metadata)
end

#record_events ⇒ Object

Note:

Currently for emitting individual events, if an error is raised then a log message will be attempted using the configured logger. For batch emitted events, the error will be allowed to bubble up. This is to prevent the unexpected loss of events if a single one is malformed.

Records the events currently in the collection then clears the state of the Collector by emptying the events stack and clearing out the metadata.



140
141
142
143
144
145
146
147
148
149
150
 
# File 'lib/conrad/collector.rb', line 140

def record_events
  Array(emitter).each do |emitter|
    if emit_as_batch?
      record_events_as_batch(emitter, events.clone)
    else
      record_individual_events(emitter, events.clone)
    end
  end
ensure
  reset_state
end