Class: LogStash::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/logstash/event.rb

Overview

the logstash event object.

An event is simply a tuple of (timestamp, data). The ‘timestamp’ is an ISO8601 timestamp. Data is anything - any message, context, references, etc that are relevant to this event.

Internally, this is represented as a hash with only two guaranteed fields.

  • “@timestamp” - an ISO8601 timestamp representing the time the event occurred at.

  • “@version” - the version of the schema. Currently “1”

They are prefixed with an “@” symbol to avoid clashing with your own custom fields.

When serialized, this is represented in JSON. For example:

{
  "@timestamp": "2013-02-09T20:39:26.234Z",
  "@version": "1",
  message: "hello world"
}

Defined Under Namespace

Classes: DeprecatedMethod

Constant Summary collapse

CHAR_PLUS = 
"+"
TIMESTAMP = 
"@timestamp"
VERSION = 
"@version"
VERSION_ONE = 
"1"
TIMESTAMP_FAILURE_TAG = 
"_timestampparsefailure"
TIMESTAMP_FAILURE_FIELD = 
"_@timestamp"
METADATA = 
"@metadata".freeze
METADATA_BRACKETS = 
"[#{METADATA}]".freeze
MIN_FLOAT_BEFORE_SCI_NOT =

Floats outside of these upper and lower bounds are forcibly converted to scientific notation by Float#to_s

0.0001
MAX_FLOAT_BEFORE_SCI_NOT = 
1000000000000000.0
DEFAULT_LOGGER = 
Cabin::Channel.get(LogStash)
@@logger = 
DEFAULT_LOGGER

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data = {}) ⇒ Event

Returns a new instance of Event.



69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/logstash/event.rb', line 69

def initialize(data = {})
  @cancelled = false
  @data = data
  @accessors = LogStash::Util::Accessors.new(data)
  @data[VERSION] ||= VERSION_ONE
  ts = @data[TIMESTAMP]
  @data[TIMESTAMP] = ts ? init_timestamp(ts) : LogStash::Timestamp.now

  @metadata = @data.delete(METADATA) || {}
  @metadata_accessors = LogStash::Util::Accessors.new(@metadata)
end

Class Method Details

.logger=(logger) ⇒ Object

set a new logger for all Event instances there is no point in changing it at runtime for other reasons than in tests/specs.

Parameters:

  • logger (Cabin::Channel) —

    logger instance that will be used by all Event instances



252
253
254
 
# File 'lib/logstash/event.rb', line 252

def self.logger=(logger)
  @@logger = logger
end

.validate_value(value) ⇒ Object

this is used by logstash-devutils spec_helper.rb to monkey patch the Event field setter []= and add systematic encoding validation on every field set in specs. TODO: (colin) this should be moved, probably in logstash-devutils ?



220
221
222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/logstash/event.rb', line 220

def self.validate_value(value)
  case value
  when String
    raise("expected UTF-8 encoding for value=#{value}, encoding=#{value.encoding.inspect}") unless value.encoding == Encoding::UTF_8
    raise("invalid UTF-8 encoding for value=#{value}, encoding=#{value.encoding.inspect}") unless value.valid_encoding?
    value
  when Array
    value.each{|v| validate_value(v)} # don't map, return original object
    value
  else
    value
  end
end

Instance Method Details

#[](fieldref) ⇒ Object 



116
117
118
119
120
121
122
123
124
 
# File 'lib/logstash/event.rb', line 116

def [](fieldref)
  if fieldref.start_with?(METADATA_BRACKETS)
    @metadata_accessors.get(fieldref[METADATA_BRACKETS.length .. -1])
  elsif fieldref == METADATA
    @metadata
  else
    @accessors.get(fieldref)
  end
end

#[]=(fieldref, value) ⇒ Object 



126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/logstash/event.rb', line 126

def []=(fieldref, value)
  if fieldref == TIMESTAMP && !value.is_a?(LogStash::Timestamp)
    raise TypeError, "The field '@timestamp' must be a (LogStash::Timestamp, not a #{value.class} (#{value})"
  end
  if fieldref.start_with?(METADATA_BRACKETS)
    @metadata_accessors.set(fieldref[METADATA_BRACKETS.length .. -1], value)
  elsif fieldref == METADATA
    @metadata = value
    @metadata_accessors = LogStash::Util::Accessors.new(@metadata)
  else
    @accessors.set(fieldref, value)
  end
end

#append(event) ⇒ Object

Append an event to this one.



172
173
174
175
176
177
178
 
# File 'lib/logstash/event.rb', line 172

def append(event)
  # non-destructively merge that event with ourselves.

  # no need to reset @accessors here because merging will not disrupt any existing field paths
  # and if new ones are created they will be picked up.
  LogStash::Util.hash_merge(@data, event.to_hash)
end

#cancel ⇒ Object 



81
82
83
 
# File 'lib/logstash/event.rb', line 81

def cancel
  @cancelled = true
end

#cancelled? ⇒ Boolean

Returns:

  • (Boolean) 


89
90
91
 
# File 'lib/logstash/event.rb', line 89

def cancelled?
  @cancelled
end

#clone ⇒ Object

Create a deep-ish copy of this event.



94
95
96
97
98
99
100
101
102
 
# File 'lib/logstash/event.rb', line 94

def clone
  copy = {}
  @data.each do |k,v|
    # TODO(sissel): Recurse if this is a hash/array?
    copy[k] = begin v.clone rescue v end
  end

  self.class.new(copy)
end

#fields ⇒ Object

Raises:



245
246
247
 
# File 'lib/logstash/event.rb', line 245

def fields
  raise DeprecatedMethod
end

#include?(fieldref) ⇒ Boolean

Returns:

  • (Boolean) 


161
162
163
164
165
166
167
168
169
 
# File 'lib/logstash/event.rb', line 161

def include?(fieldref)
  if fieldref.start_with?(METADATA_BRACKETS)
    @metadata_accessors.include?(fieldref[METADATA_BRACKETS.length .. -1])
  elsif fieldref == METADATA
    true
  else
    @accessors.include?(fieldref)
  end
end

#overwrite(event) ⇒ Object 



149
150
151
152
153
154
155
156
157
158
159
 
# File 'lib/logstash/event.rb', line 149

def overwrite(event)
  # pickup new event @data and also pickup @accessors
  # otherwise it will be pointing on previous data
  @data = event.instance_variable_get(:@data)
  @accessors = event.instance_variable_get(:@accessors)

  #convert timestamp if it is a String
  if @data[TIMESTAMP].is_a?(String)
    @data[TIMESTAMP] = LogStash::Timestamp.parse_iso8601(@data[TIMESTAMP])
  end
end

#remove(fieldref) ⇒ Object

Remove a field or field reference. Returns the value of that field when deleted



181
182
183
 
# File 'lib/logstash/event.rb', line 181

def remove(fieldref)
  @accessors.del(fieldref)
end

#ruby_timestamp ⇒ Object

Raises:



241
242
243
 
# File 'lib/logstash/event.rb', line 241

def ruby_timestamp
  raise DeprecatedMethod
end

#sprintf(format) ⇒ Object

sprintf. This could use a better method name. The idea is to take an event and convert it to a string based on any format values, delimited by %foo where ‘foo’ is a field or metadata member.

For example, if the event has type == “foo” and host == “bar” then this string:

"type is %{type} and source is %{host}"

will return

"type is foo and source is bar"

If a %name value is an array, then we will join by ‘,’ If a %name value does not exist, then no substitution occurs.



198
199
200
 
# File 'lib/logstash/event.rb', line 198

def sprintf(format)
  LogStash::StringInterpolation.evaluate(self, format)
end

#tag(value) ⇒ Object 



202
203
204
205
206
 
# File 'lib/logstash/event.rb', line 202

def tag(value)
  # Generalize this method for more usability
  self["tags"] ||= []
  self["tags"] << value unless self["tags"].include?(value)
end

#timestamp ⇒ Object 



108
109
110
 
# File 'lib/logstash/event.rb', line 108

def timestamp
  @data[TIMESTAMP]
end

#timestamp=(val) ⇒ Object 



112
113
114
 
# File 'lib/logstash/event.rb', line 112

def timestamp=(val)
  @data[TIMESTAMP] = val
end

#to_hash ⇒ Object 



145
146
147
 
# File 'lib/logstash/event.rb', line 145

def to_hash
  @data
end

#to_hash_with_metadata ⇒ Object 



208
209
210
 
# File 'lib/logstash/event.rb', line 208

def to_hash_with_metadata
  @metadata.empty? ? to_hash : to_hash.merge(METADATA => @metadata)
end

#to_json(*args) ⇒ Object 



140
141
142
143
 
# File 'lib/logstash/event.rb', line 140

def to_json(*args)
  # ignore arguments to respect accepted to_json method signature
  LogStash::Json.dump(@data)
end

#to_json_with_metadata(*args) ⇒ Object 



212
213
214
215
 
# File 'lib/logstash/event.rb', line 212

def to_json_with_metadata(*args)
  # ignore arguments to respect accepted to_json method signature
  LogStash::Json.dump(to_hash_with_metadata)
end

#to_s ⇒ Object 



104
105
106
 
# File 'lib/logstash/event.rb', line 104

def to_s
  "#{timestamp.to_iso8601} #{self.sprintf("%{host} %{message}")}"
end

#uncancel ⇒ Object 



85
86
87
 
# File 'lib/logstash/event.rb', line 85

def uncancel
  @cancelled = false
end

#unix_timestamp ⇒ Object

depracated public methods TODO: (colin) since these depracated mothods are still exposed in 2.x we should remove them in 3.0

Raises:



237
238
239
 
# File 'lib/logstash/event.rb', line 237

def unix_timestamp
  raise DeprecatedMethod
end