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



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

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



130
131
132
133
134
135
136
137
138
139
 
# File 'lib/lumberjack/log_entry.rb', line 130

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



121
122
123
 
# File 'lib/lumberjack/log_entry.rb', line 121

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



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

def nested_attributes
  Utils.expand_attributes(attributes)
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

#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