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"
}

Constants

CHAR_PLUS
TIMESTAMP
VERSION
VERSION_ONE

Public Class Methods

new(data={}) click to toggle source
# 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

[](str) click to toggle source

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

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

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
fields() click to toggle source
# File lib/logstash/event.rb, line 162
def fields
  raise DeprecatedMethod
end
include?(key) click to toggle source
# File lib/logstash/event.rb, line 181
def include?(key)
  return !self[key].nil?
end
overwrite(event) click to toggle source
# File lib/logstash/event.rb, line 176
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 195
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 113
def ruby_timestamp
  raise DeprecatedMethod
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 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
tag(value) click to toggle source
# 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
timestamp() click to toggle source
# File lib/logstash/event.rb, line 106
def timestamp; return @data[TIMESTAMP]; end
timestamp=(val) click to toggle source
# File lib/logstash/event.rb, line 107
def timestamp=(val); return @data[TIMESTAMP] = val; end
to_hash() click to toggle source
# File lib/logstash/event.rb, line 171
def to_hash
  return @data
end
to_json(*args) click to toggle source
# File lib/logstash/event.rb, line 167
def to_json(*args)
  return @data.to_json(*args) 
end
to_s() click to toggle source
# File lib/logstash/event.rb, line 95
def to_s
  return self.sprintf("%{+yyyy-MM-dd'T'HH:mm:ss.SSSZ} %{host} %{message}")
end
uncancel() click to toggle source
# File lib/logstash/event.rb, line 73
def uncancel
  @cancelled = false
end
unix_timestamp() click to toggle source
# File lib/logstash/event.rb, line 109
def unix_timestamp
  raise DeprecatedMethod
end