Class: Lumberjack::LogEntry

Inherits:
Object
  • Object
show all
Defined in:
lib/lumberjack/log_entry.rb

Overview

A structured representation of a single log entry containing the message, metadata, and contextual information. LogEntry objects are immutable data structures that capture all relevant information about a logging event, including timing, severity, source identification, and custom attributes.

This class serves as the fundamental data structure passed between loggers, formatters, and output devices throughout the Lumberjack logging pipeline. Each entry maintains consistent structure while supporting flexible attribute attachment for contextual logging scenarios.

Constant Summary collapse

TIME_FORMAT = 
"%Y-%m-%dT%H:%M:%S.%3N"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(time, severity, message, progname, pid, attributes) ⇒ LogEntry

Create a new log entry with the specified components. The entry captures all relevant information about a logging event in a structured format.

Parameters:

  • time (Time) —

    The timestamp when the log entry was created

  • severity (Integer, String, Symbol) —

    The severity level, accepts numeric levels or labels

  • message (String) —

    The primary log message content

  • progname (String, nil) —

    The name of the program or component generating the entry

  • pid (Integer) —

    The process ID of the logging process

  • attributes (Hash<String, Object>, nil) —

    Custom attributes to associate with the entry



39
40
41
42
43
44
45
46
 
# File 'lib/lumberjack/log_entry.rb', line 39

def initialize(time, severity, message, progname, pid, attributes)
  @time = time
  @severity = (severity.is_a?(Integer) ? severity : Severity.label_to_level(severity))
  @message = message
  @progname = progname
  @pid = pid
  @attributes = flatten_attributes(attributes) if attributes.is_a?(Hash)
end

Instance Attribute Details

#attributes ⇒ Hash<String, Object>

Returns Custom attributes associated with the log entry.

Returns:

  • (Hash<String, Object>) —

    Custom attributes associated with the log entry



26
 
# File 'lib/lumberjack/log_entry.rb', line 26

attr_accessor :time, :message, :severity, :progname, :pid, :attributes

#message ⇒ String

Returns The primary log message content.

Returns:

  • (String) —

    The primary log message content



26
 
# File 'lib/lumberjack/log_entry.rb', line 26

attr_accessor :time, :message, :severity, :progname, :pid, :attributes

#pid ⇒ Integer

Returns The process ID of the logging process.

Returns:

  • (Integer) —

    The process ID of the logging process



26
 
# File 'lib/lumberjack/log_entry.rb', line 26

attr_accessor :time, :message, :severity, :progname, :pid, :attributes

#progname ⇒ String

Returns The name of the program or component that generated the entry.

Returns:

  • (String) —

    The name of the program or component that generated the entry



26
 
# File 'lib/lumberjack/log_entry.rb', line 26

attr_accessor :time, :message, :severity, :progname, :pid, :attributes

#severity ⇒ Integer

Returns The numeric severity level of the log entry.

Returns:

  • (Integer) —

    The numeric severity level of the log entry



26
 
# File 'lib/lumberjack/log_entry.rb', line 26

attr_accessor :time, :message, :severity, :progname, :pid, :attributes

#time ⇒ Time

Returns The timestamp when the log entry was created.

Returns:

  • (Time) —

    The timestamp when the log entry was created



26
27
28
 
# File 'lib/lumberjack/log_entry.rb', line 26

def time
  @time
end

Instance Method Details

#==(other) ⇒ Boolean

Compare this log entry with another for equality. Two log entries are considered equal if all their components match exactly.

Parameters:

  • other (Object) —

    The object to compare against

Returns:

  • (Boolean) —

    True if the entries are identical, false otherwise



85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/lumberjack/log_entry.rb', line 85

def ==(other)
  return true if equal?(other)
  return false unless other.is_a?(LogEntry)

  time == other.time &&
    severity == other.severity &&
    message == other.message &&
    progname == other.progname &&
    pid == other.pid &&
    attributes == other.attributes
end

#[](name) ⇒ Object?

Access an attribute value by name. Supports both simple and nested attribute access using dot notation for hierarchical data structures.

Parameters:

  • name (String, Symbol) —

    The attribute name, supports dot notation for nested access

Returns:

  • (Object, nil) —

    The attribute value or nil if the attribute does not exist



113
114
115
116
117
 
# File 'lib/lumberjack/log_entry.rb', line 113

def [](name)
  return nil if attributes.nil?

  AttributesHelper.new(attributes)[name]
end

#as_json ⇒ Hash

Convert the log entry into a hash suitable for JSON serialization. Attributes will be expanded into a nested structure (i.e. { “user.id” => 123 } becomes ‘{ “user” => { “id” => 123 } }). Severities will be converted to their string labels.

Returns:

  • (Hash) —

    The JSON representation of the log entry



163
164
165
166
167
168
169
170
171
172
 
# File 'lib/lumberjack/log_entry.rb', line 163

def as_json
  {
    "time" => time,
    "severity" => severity_label,
    "message" => message,
    "progname" => progname,
    "pid" => pid,
    "attributes" => Utils.expand_attributes(attributes)
  }
end

#empty? ⇒ Boolean

Determine if the log entry contains no meaningful content. An entry is considered empty if it has no message content and no attributes.

Returns:

  • (Boolean) —

    True if the entry is empty, false otherwise



154
155
156
 
# File 'lib/lumberjack/log_entry.rb', line 154

def empty?
  (message.nil? || message == "") && (attributes.nil? || attributes.empty?)
end

#inspect ⇒ String

Return a string representation suitable for debugging and inspection.

Returns:

  • (String) —

    The same as #to_s



76
77
78
 
# File 'lib/lumberjack/log_entry.rb', line 76

def inspect
  to_s
end

#nested_attributes ⇒ Hash

Expand flat attributes with dot notation into a nested hash structure. Attributes containing dots in their names are converted into hierarchical nested hashes for structured data representation.

Returns:

  • (Hash) —

    The attributes expanded into a nested structure



135
136
137
 
# File 'lib/lumberjack/log_entry.rb', line 135

def nested_attributes
  Utils.expand_attributes(attributes)
end

#nested_tags ⇒ Hash

Deprecated.

Use #nested_attributes instead.

Alias for nested_attributes to provide API compatibility with version 1.x. This method will eventually be removed.

Returns:

  • (Hash) 


144
145
146
147
148
 
# File 'lib/lumberjack/log_entry.rb', line 144

def nested_tags
  Utils.deprecated("LogEntry#nested_tags", "Lumberjack::LogEntry#nested_tags is deprecated and will be removed in version 2.1; use nested_attributes instead.") do
    nested_attributes
  end
end

#severity_data ⇒ Object

Get the data corresponding to the severity. This include variations on the severity label.



56
57
58
 
# File 'lib/lumberjack/log_entry.rb', line 56

def severity_data
  Severity.data(severity)
end

#severity_label ⇒ String

Get the human-readable severity label corresponding to the numeric severity level.

Returns:

  • (String) —

    The severity label (DEBUG, INFO, WARN, ERROR, FATAL, or UNKNOWN)



51
52
53
 
# File 'lib/lumberjack/log_entry.rb', line 51

def severity_label
  severity_data.label
end

#tag(name) ⇒ Hash

Deprecated.

Use #[] instead.

Alias method for #[] to provide backward compatibility with version 1.x API. This method will eventually be removed.

Returns:

  • (Hash) 


124
125
126
127
128
 
# File 'lib/lumberjack/log_entry.rb', line 124

def tag(name)
  Utils.deprecated("LogEntry#tag", "Lumberjack::LogEntry#tag is deprecated and will be removed in version 2.1; use [] instead.") do
    self[name]
  end
end

#tags ⇒ Hash?

Deprecated.

Use #attributes instead.

Alias for tags to provide backward compatibility with version 1.x API. This method will eventually be removed.

Returns:

  • (Hash, nil) —

    The attributes of the log entry.



102
103
104
105
106
 
# File 'lib/lumberjack/log_entry.rb', line 102

def tags
  Utils.deprecated("LogEntry#tags", "Lumberjack::LogEntry#tags is deprecated and will be removed in version 2.1; use attributes instead.") do
    attributes
  end
end

#to_s ⇒ String

Generate a formatted string representation of the log entry suitable for human consumption. Includes timestamp, severity, program name, process ID, attributes, and the main message.

Returns:

  • (String) —

    A formatted string representation of the complete log entry



65
66
67
68
69
70
71
 
# File 'lib/lumberjack/log_entry.rb', line 65

def to_s
  msg = +"[#{time.strftime(TIME_FORMAT)} #{severity_label} #{progname}(#{pid})] #{message}"
  attributes&.each do |key, value|
    msg << " [#{key}:#{value}]"
  end
  msg
end