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.

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

included(klass) click to toggle source

Add class methods on inclusion.

# File lib/logstash/event.rb, line 62
def self.included(klass)
  klass.extend(ClassMethods)
end
new(data={}) click to toggle source
# 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

[](str) click to toggle source

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
[]=(str, value) click to toggle source
# 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(event) click to toggle source

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
cancel() click to toggle source
# File lib/logstash/event.rb, line 74
def cancel
  @cancelled = true
end
cancelled?() click to toggle source
# File lib/logstash/event.rb, line 84
def cancelled?
  return @cancelled
end
clone() click to toggle source

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
fields() click to toggle source
# File lib/logstash/event.rb, line 163
def fields
  raise DeprecatedMethod
end
include?(key) click to toggle source
# File lib/logstash/event.rb, line 182
def include?(key)
  return !self[key].nil?
end
message=(value) click to toggle source
# File lib/logstash/event.rb, line 261
def message=(value); self["message"] = value; end
overwrite(event) click to toggle source
# File lib/logstash/event.rb, line 177
def overwrite(event)
  @data = event.to_hash
end
remove(str) click to toggle source

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
ruby_timestamp() click to toggle source
# File lib/logstash/event.rb, line 119
def ruby_timestamp
  raise DeprecatedMethod
end
source=(value) click to toggle source
# File lib/logstash/event.rb, line 262
def source=(value); self["source"] = value; end
sprintf(format) click to toggle source

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
tag(value) click to toggle source
# 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
tags() click to toggle source
# File lib/logstash/event.rb, line 260
def tags; return self["tags"]; end
tags=(value) click to toggle source

Shims to remove after event v1 is the default.

# File lib/logstash/event.rb, line 259
def tags=(value); self["tags"] = value; end
timestamp() click to toggle source
# File lib/logstash/event.rb, line 112
def timestamp; return @data["@timestamp"]; end
timestamp=(val) click to toggle source
# File lib/logstash/event.rb, line 113
def timestamp=(val); return @data["@timestamp"] = val; end
to_hash() click to toggle source
# File lib/logstash/event.rb, line 172
def to_hash
  return @data
end
to_json(*args) click to toggle source
# File lib/logstash/event.rb, line 168
def to_json(*args)
  return @data.to_json(*args) 
end
to_s() click to toggle source
# File lib/logstash/event.rb, line 101
def to_s
  return self.sprintf("%{+yyyy-MM-dd'T'HH:mm:ss.SSSZ} %{host} %{message}")
end
type() click to toggle source
# File lib/logstash/event.rb, line 264
def type; return self["type"]; end
type=(value) click to toggle source
# File lib/logstash/event.rb, line 263
def type=(value); self["type"] = value; end
uncancel() click to toggle source
# File lib/logstash/event.rb, line 79
def uncancel
  @cancelled = false
end
unix_timestamp() click to toggle source
# File lib/logstash/event.rb, line 115
def unix_timestamp
  raise DeprecatedMethod
end