Class: Google::Logging::Message

Inherits:
Object
  • Object
show all
Defined in:
lib/google/logging/message.rb

Overview

A log message that can be formatted either as a normal text log entry or as a structured log entry suitable for Google Cloud Logging.

A log message has a “body” which consists of either a string message, a JSON object (i.e. a Hash whose values are typically strings or numbers but could be nested arrays and hashes), or both. It also includes several additional optional fields used by the Google Cloud Logging backend.

Most log formatters will render the message body as a string and ignore the other attributes. The StructuredFormatter, however, will format the full message data in the JSON format understood by the Google logging agent.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(message: nil, fields: nil, timestamp: nil, source_location: nil, insert_id: nil, trace: nil, span_id: nil, trace_sampled: nil, labels: nil) ⇒ Message

Low-level constructor for a logging message. All arguments are optional, with the exception that at least one of ‘:message` and `:fields` must be provided.

Parameters:

  • message (String) (defaults to: nil) —

    The main log message as a string.

  • fields (Hash{String=>Object}) (defaults to: nil) —

    The log message as a set of key-value pairs representing a JSON object.

  • timestamp (Time, Numeric, :now) (defaults to: nil) —

    The timestamp for the log entry. Can be provided as a Time object, a Numeric indicating the seconds since epoch, or ‘:now` to use the current time. Optional.

  • source_location (SourceLocation, Hash, :caller, nil) (defaults to: nil) —

    The source location for the log entry. Can be provided as a SourceLocation object, a Hash containing exactly the keys ‘:file`, `:line`, and `:function`, or `:caller` to use the location of the caller. Optional.

  • insert_id (String) (defaults to: nil) —

    A unique ID for this log entry that could be used on the backend to dedup messages. Optional.

  • trace (String) (defaults to: nil) —

    A Google Cloud Trace resource name. Optional.

  • span_id (String) (defaults to: nil) —

    The trace span containing this entry. Optional.

  • trace_sampled (boolean) (defaults to: nil) —

    Whether this trace is sampled. Optional.

  • labels (Hash{String=>String}) (defaults to: nil) —

    Optional metadata.



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/google/logging/message.rb', line 98

def initialize message: nil,
               fields: nil,
               timestamp: nil,
               source_location: nil,
               insert_id: nil,
               trace: nil,
               span_id: nil,
               trace_sampled: nil,
               labels: nil
  @fields = interpret_fields fields
  @message, @full_message = interpret_message message, @fields
  @timestamp = interpret_timestamp timestamp
  @source_location = interpret_source_location source_location
  @insert_id = interpret_string insert_id
  @trace = interpret_string trace
  @span_id = interpret_string span_id
  @trace_sampled = interpret_boolean trace_sampled
  @labels = interpret_labels labels
end

Instance Attribute Details

#fields ⇒ Hash{String=>Object}? (readonly)

Returns The log message as a set of key-value pairs, or nil if not present.

Returns:

  • (Hash{String=>Object}, nil) —

    The log message as a set of key-value pairs, or nil if not present.



137
138
139
 
# File 'lib/google/logging/message.rb', line 137

def fields
  @fields
end

#full_message ⇒ String (readonly) Also known as: inspect

Returns A full string representation of the message and fields as rendered in the standard logger formatter.

Returns:

  • (String) —

    A full string representation of the message and fields as rendered in the standard logger formatter.



130
131
132
 
# File 'lib/google/logging/message.rb', line 130

def full_message
  @full_message
end

#insert_id ⇒ String? (readonly)

Returns The unique ID for this log entry that could be used on the backend to dedup messages, or nil if not present.

Returns:

  • (String, nil) —

    The unique ID for this log entry that could be used on the backend to dedup messages, or nil if not present.



155
156
157
 
# File 'lib/google/logging/message.rb', line 155

def insert_id
  @insert_id
end

#labels ⇒ Hash{String=>String}? (readonly)

Returns Metadata, or nil if not present.

Returns:

  • (Hash{String=>String}, nil) —

    Metadata, or nil if not present.



179
180
181
 
# File 'lib/google/logging/message.rb', line 179

def labels
  @labels
end

#message ⇒ String (readonly) Also known as: to_s

Returns The message as a string. This is always present as a nonempty string, and can be reliably used as the “display” of this log entry in a list of entries.

Returns:

  • (String) —

    The message as a string. This is always present as a nonempty string, and can be reliably used as the “display” of this log entry in a list of entries.



123
124
125
 
# File 'lib/google/logging/message.rb', line 123

def message
  @message
end

#source_location ⇒ SourceLocation? (readonly)

Returns The source location for the log entry, or nil if not present.

Returns:

  • (SourceLocation, nil) —

    The source location for the log entry, or nil if not present.



149
150
151
 
# File 'lib/google/logging/message.rb', line 149

def source_location
  @source_location
end

#span_id ⇒ String? (readonly)

Returns The trace span containing this entry, or nil if not present.

Returns:

  • (String, nil) —

    The trace span containing this entry, or nil if not present.



167
168
169
 
# File 'lib/google/logging/message.rb', line 167

def span_id
  @span_id
end

#timestamp ⇒ Time? (readonly)

Returns The timestamp for the log entry, or nil if not present.

Returns:

  • (Time, nil) —

    The timestamp for the log entry, or nil if not present.



143
144
145
 
# File 'lib/google/logging/message.rb', line 143

def timestamp
  @timestamp
end

#trace ⇒ String? (readonly)

Returns The Google Cloud Trace resource name, or nil if not present.

Returns:

  • (String, nil) —

    The Google Cloud Trace resource name, or nil if not present.



161
162
163
 
# File 'lib/google/logging/message.rb', line 161

def trace
  @trace
end

#trace_sampled ⇒ true, ... (readonly) Also known as: trace_sampled?

Returns Whether this trace is sampled, or nil if not present or known.

Returns:

  • (true, false, nil) —

    Whether this trace is sampled, or nil if not present or known.



173
174
175
 
# File 'lib/google/logging/message.rb', line 173

def trace_sampled
  @trace_sampled
end

Class Method Details

.from(input) ⇒ Message

Create a log message from an input object, which can be any of:

  • An existing Message object.

  • A Hash. Symbol keys are used as keyword arguments to the #initialize constructor. String keys are treated as fields in the JSON payload.

  • Any other object is converted to a string with ‘to_s` and used as a simple text payload.

Parameters:

  • input (Object) —

    A log message input object.

Returns:



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/google/logging/message.rb', line 50

def self.from input
  case input
  when Hash
    kwargs = {}
    fields = nil
    input.each do |k, v|
      if k.is_a? Symbol
        kwargs[k] = v
      else
        (fields ||= {})[k.to_s] = v
      end
    end
    if kwargs[:fields] && fields
      kwargs[:fields].merge! fields
    else
      kwargs[:fields] ||= fields
    end
    new(**kwargs)
  when Message
    input
  else
    new message: input.to_s
  end
end

Instance Method Details

#==(other) ⇒ Object Also known as: eql? 



200
201
202
203
204
205
206
207
208
209
210
211
 
# File 'lib/google/logging/message.rb', line 200

def == other
  return false unless other.is_a? Message
  message == other.message &&
    fields == other.fields &&
    timestamp == other.timestamp &&
    source_location == other.source_location &&
    insert_id == other.insert_id &&
    trace == other.trace &&
    span_id == other.span_id &&
    trace_sampled? == other.trace_sampled? &&
    labels == other.labels
end

#hash ⇒ Object 



215
216
217
 
# File 'lib/google/logging/message.rb', line 215

def hash
  [message, fields, timestamp, source_location, insert_id, trace, span_id, trace_sampled, labels].hash
end

#to_h ⇒ Hash

Returns A hash of kwargs that can be passed to the constructor to clone this message.

Returns:

  • (Hash) —

    A hash of kwargs that can be passed to the constructor to clone this message.



185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/google/logging/message.rb', line 185

def to_h
  {
    message: @message,
    fields: @fields.dup,
    timestamp: @timestamp,
    source_location: @source_location,
    insert_id: @insert_id,
    trace: @trace,
    span_id: @span_id,
    trace_sampled: @trace_sampled,
    labels: @labels.dup
  }
end