class LogStash::Event
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" }
Constants
- CHAR_PLUS
- TIMESTAMP
- VERSION
- VERSION_ONE
Public Class Methods
# File lib/logstash/event.rb, line 52 def initialize(data={}) @cancelled = false @data = data data[VERSION] = VERSION_ONE if !@data.include?(VERSION) if data.include?(TIMESTAMP) t = data[TIMESTAMP] if t.is_a?(String) data[TIMESTAMP] = LogStash::Time.parse_iso8601(t) end else data[TIMESTAMP] = ::Time.now.utc end end
Public Instance Methods
field-related access
# File lib/logstash/event.rb, line 119 def [](str) if str[0,1] == CHAR_PLUS # nothing? else return LogStash::Util::FieldReference.exec(str, @data) end end
# File lib/logstash/event.rb, line 128 def []=(str, value) if str == TIMESTAMP && !value.is_a?(Time) raise TypeError, "The field '@timestamp' must be a Time, not a #{value.class} (#{value})" end r = LogStash::Util::FieldReference.exec(str, @data) do |obj, key| obj[key] = value end # The assignment can fail if the given field reference (str) does not exist # In this case, we'll want to set the value manually. if r.nil? # TODO(sissel): Implement this in LogStash::Util::FieldReference if str[0,1] != "[" return @data[str] = value end # No existing element was found, so let's set one. *parents, key = str.scan(/(?<=\[)[^\]]+(?=\])/) obj = @data parents.each do |p| if obj.include?(p) obj = obj[p] else obj[p] = {} obj = obj[p] end end obj[key] = value end return value end
Append an event to this one.
# File lib/logstash/event.rb, line 187 def append(event) # non-destructively merge that event with ourselves. LogStash::Util.hash_merge(@data, event.to_hash) end
# File lib/logstash/event.rb, line 68 def cancel @cancelled = true end
# File lib/logstash/event.rb, line 78 def cancelled? return @cancelled end
Create a deep-ish copy of this event.
# File lib/logstash/event.rb, line 84 def clone copy = {} @data.each do |k,v| # TODO(sissel): Recurse if this is a hash/array? copy[k] = v.clone end return self.class.new(copy) end
# File lib/logstash/event.rb, line 162 def fields raise DeprecatedMethod end
# File lib/logstash/event.rb, line 181 def include?(key) return !self[key].nil? end
# File lib/logstash/event.rb, line 176 def overwrite(event) @data = event.to_hash end
Remove a field or field reference. Returns the value of that field when deleted
# File lib/logstash/event.rb, line 195 def remove(str) return LogStash::Util::FieldReference.exec(str, @data) do |obj, key| next obj.delete(key) end end
# File lib/logstash/event.rb, line 113 def ruby_timestamp raise DeprecatedMethod end
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 source == “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.
TODO(sissel): It is not clear what the value of a field that is an array (or hash?) should be. Join by comma? Something else?
# File lib/logstash/event.rb, line 218 def sprintf(format) format = format.to_s if format.index("%").nil? return format end return format.gsub(/%\{[^}]+\}/) do |tok| # Take the inside of the %{ ... } key = tok[2 ... -1] if key == "+%s" # Got %{+%s}, support for unix epoch time next @data["@timestamp"].to_i elsif key[0,1] == "+" t = @data["@timestamp"] formatter = org.joda.time.format.DateTimeFormat.forPattern(key[1 .. -1])\ .withZone(org.joda.time.DateTimeZone::UTC) #next org.joda.time.Instant.new(t.tv_sec * 1000 + t.tv_usec / 1000).toDateTime.toString(formatter) # Invoke a specific Instant constructor to avoid this warning in JRuby # > ambiguous Java methods found, using org.joda.time.Instant(long) org.joda.time.Instant.java_class.constructor(Java::long).new_instance( t.tv_sec * 1000 + t.tv_usec / 1000 ).to_java.toDateTime.toString(formatter) else value = self[key] case value when nil tok # leave the %{foo} if this field does not exist in this event. when Array value.join(",") # Join by ',' if value is an array when Hash value.to_json # Convert hashes to json else value # otherwise return the value end # case value end # 'key' checking end # format.gsub... end
# File lib/logstash/event.rb, line 257 def tag(value) # Generalize this method for more usability self["tags"] ||= [] self["tags"] << value unless self["tags"].include?(value) end
# File lib/logstash/event.rb, line 106 def timestamp; return @data[TIMESTAMP]; end
# File lib/logstash/event.rb, line 107 def timestamp=(val); return @data[TIMESTAMP] = val; end
# File lib/logstash/event.rb, line 171 def to_hash return @data end
# File lib/logstash/event.rb, line 167 def to_json(*args) return @data.to_json(*args) end
# File lib/logstash/event.rb, line 95 def to_s return self.sprintf("%{+yyyy-MM-dd'T'HH:mm:ss.SSSZ} %{host} %{message}") end
# File lib/logstash/event.rb, line 73 def uncancel @cancelled = false end
# File lib/logstash/event.rb, line 109 def unix_timestamp raise DeprecatedMethod end