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" }
Public Class Methods
Add class methods on inclusion.
# File lib/logstash/event.rb, line 62 def self.included(klass) klass.extend(ClassMethods) end
# File lib/logstash/event.rb, line 45 def initialize(data={}) @cancelled = false @data = data if data.include?("@timestamp") t = data["@timestamp"] if t.is_a?(String) data["@timestamp"] = Time.parse(t).gmtime end else data["@timestamp"] = ::Time.now.utc end data["@version"] = "1" if !@data.include?("@version") end
Public Instance Methods
field-related access
# File lib/logstash/event.rb, line 125 def [](str) if str[0,1] == "+" else return LogStash::Util::FieldReference.exec(str, @data) end end
# File lib/logstash/event.rb, line 133 def []=(str, value) 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 188 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 74 def cancel @cancelled = true end
# File lib/logstash/event.rb, line 84 def cancelled? return @cancelled end
Create a deep-ish copy of this event.
# File lib/logstash/event.rb, line 90 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 163 def fields raise DeprecatedMethod end
# File lib/logstash/event.rb, line 182 def include?(key) return !self[key].nil? end
# File lib/logstash/event.rb, line 261 def message=(value); self["message"] = value; end
# File lib/logstash/event.rb, line 177 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 196 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 119 def ruby_timestamp raise DeprecatedMethod end
# File lib/logstash/event.rb, line 262 def source=(value); self["source"] = value; 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 219 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 267 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 112 def timestamp; return @data["@timestamp"]; end
# File lib/logstash/event.rb, line 113 def timestamp=(val); return @data["@timestamp"] = val; end
# File lib/logstash/event.rb, line 172 def to_hash return @data end
# File lib/logstash/event.rb, line 168 def to_json(*args) return @data.to_json(*args) end
# File lib/logstash/event.rb, line 101 def to_s return self.sprintf("%{+yyyy-MM-dd'T'HH:mm:ss.SSSZ} %{host} %{message}") end
# File lib/logstash/event.rb, line 264 def type; return self["type"]; end
# File lib/logstash/event.rb, line 263 def type=(value); self["type"] = value; end
# File lib/logstash/event.rb, line 79 def uncancel @cancelled = false end
# File lib/logstash/event.rb, line 115 def unix_timestamp raise DeprecatedMethod end