Class: Google::Cloud::Logging::Logger

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

Overview

Logger

An API-compatible replacement for ruby's Logger that logs to the Stackdriver Logging Service.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

resource = logging.resource "gae_app",
                            module_id: "1",
                            version_id: "20150925t173233"

logger = logging.logger "my_app_log", resource, env: :production
logger.info "Job started."

Defined Under Namespace

Classes: RequestInfo

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(writer, log_name, resource, labels = nil) ⇒ Google::Cloud::Logging::Logger

Create a new Logger instance.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

writer = logging.async_writer max_queue_size: 1000

resource = logging.resource "gae_app", labels: {
                              "module_id" => "1",
                              "version_id" => "20150925t173233"
                            }

logger = Google::Cloud::Logging::Logger.new writer,
                                            "my_app_log",
                                            resource,
                                            env: :production
logger.info "Job started."

Parameters:

  • writer (#write_entries) —

    The object that will transmit log entries. Generally, to create a logger that blocks on transmitting log entries, pass the Project; otherwise, to create a logger that transmits log entries in the background, pass an AsyncWriter. You may also pass any other object that responds to #write_entries.

  • log_name (String) —

    A log resource name to be associated with the written log entries.

  • resource (Google::Cloud::Logging::Resource) —

    The monitored resource to be associated with written log entries.

  • labels (Hash) (defaults to: nil) —

    A set of user-defined data to be associated with written log entries.



143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/google/cloud/logging/logger.rb', line 143

def initialize writer, log_name, resource, labels = nil
  @writer = writer
  @log_name = log_name
  @resource = resource
  @labels = labels
  @level = 0 # DEBUG is the default behavior
  @request_info = {}
  @closed = false
  # Unused, but present for API compatibility
  @formatter = ::Logger::Formatter.new
  @datetime_format = ""

  # The writer is usually a Project or AsyncWriter.
  logging = @writer.respond_to?(:logging) ? @writer.logging : @writer
  @project = logging.project if logging.respond_to? :project
end

Instance Attribute Details

#datetime_format ⇒ Object

This logger does not use a formatter, but it implements this attribute for API compatibility with the standard Logger.



83
84
85
 
# File 'lib/google/cloud/logging/logger.rb', line 83

def datetime_format
  @datetime_format
end

#formatter ⇒ Object

This logger does not use a formatter, but it provides a default Logger::Formatter for API compatibility with the standard Logger.



78
79
80
 
# File 'lib/google/cloud/logging/logger.rb', line 78

def formatter
  @formatter
end

#labels ⇒ Object (readonly)

The Google Cloud labels to write the log entry with.



68
69
70
 
# File 'lib/google/cloud/logging/logger.rb', line 68

def labels
  @labels
end

#level ⇒ Object Also known as: sev_threshold

The logging severity threshold (e.g. Logger::INFO)



72
73
74
 
# File 'lib/google/cloud/logging/logger.rb', line 72

def level
  @level
end

#log_name ⇒ Object (readonly) Also known as: progname

The Google Cloud log_name to write the log entry with.



59
60
61
 
# File 'lib/google/cloud/logging/logger.rb', line 59

def log_name
  @log_name
end

#project ⇒ Object

The project ID this logger is sending data to. If set, this value is used to set the trace field of log entries.



88
89
90
 
# File 'lib/google/cloud/logging/logger.rb', line 88

def project
  @project
end

#resource ⇒ Object (readonly)

The Google Cloud resource to write the log entry with.



64
65
66
 
# File 'lib/google/cloud/logging/logger.rb', line 64

def resource
  @resource
end

#writer ⇒ Object (readonly)

The Google Cloud writer object that calls to #write_entries are made on. Either an AsyncWriter or Project object.



55
56
57
 
# File 'lib/google/cloud/logging/logger.rb', line 55

def writer
  @writer
end

Instance Method Details

#<<(msg) ⇒ Object

Logs the given message at UNKNOWN severity.

Parameters:

  • msg (String) —

    The log entry payload as a string.



306
307
308
309
 
# File 'lib/google/cloud/logging/logger.rb', line 306

def << msg
  unknown msg
  self
end

#add(severity, message = nil, progname = nil) { ... } ⇒ Object Also known as: log

Log a message if the given severity is high enough. This is the generic logging method. Users will be more inclined to use #debug, #info, #warn, #error, and #fatal.

Parameters:

  • severity (Integer, String, Symbol) —

    the integer code for or the name of the severity level

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

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer).

Yields:

  • Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.



283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
 
# File 'lib/google/cloud/logging/logger.rb', line 283

def add severity, message = nil, progname = nil
  severity = derive_severity(severity) || 5 # 5 is UNKNOWN/DEFAULT
  return true if severity < @level

  if message.nil?
    if block_given?
      message = yield
    else
      message = progname
      # progname = nil # TODO: Figure out what to do with the progname
    end
  end

  write_entry severity, message unless @closed
  true
end

#add_request_info(info: nil, trace_id: nil, log_name: nil) ⇒ Object

Associate request data with the current Thread. You may provide either the individual pieces of data (trace ID, log name) or a populated RequestInfo object.

Parameters:

  • info (RequestInfo) —

    Info about the current request. Optional. If not present, a new RequestInfo is created using the remaining parameters.

  • trace_id (String, nil) —

    The trace ID, or nil if no trace ID should be logged.

  • log_name (String, nil) —

    The log name to use, or nil to use this logger's default.



418
419
420
421
422
423
424
425
426
427
428
429
430
 
# File 'lib/google/cloud/logging/logger.rb', line 418

def add_request_info info: nil,
                     trace_id: nil,
                     log_name: nil
  info ||= RequestInfo.new trace_id, log_name
  @request_info[current_thread_id] = info

  # Start removing old entries if hash gets too large.
  # This should never happen, because middleware should automatically
  # remove entries when a request is finished
  @request_info.shift while @request_info.size > 10_000

  info
end

#add_trace_id(trace_id) ⇒ Object

Deprecated.

Use add_request_info

Track a given trace_id by associating it with the current Thread



401
402
403
 
# File 'lib/google/cloud/logging/logger.rb', line 401

def add_trace_id trace_id
  add_request_id trace_id: trace_id
end

#close ⇒ Object

Close the logging "device". This effectively disables logging from this logger; any further log messages will be silently ignored. The logger may be re-enabled by calling #reopen.



378
379
380
381
 
# File 'lib/google/cloud/logging/logger.rb', line 378

def close
  @closed = true
  self
end

#debug(message = nil) { ... } ⇒ Object

Log a DEBUG entry.

Parameters:

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

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer).

Yields:

  • Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.



170
171
172
173
174
175
176
 
# File 'lib/google/cloud/logging/logger.rb', line 170

def debug message = nil, &block
  if block_given?
    add 0, nil, message, &block
  else
    add 0, message, nil, &block
  end
end

#debug? ⇒ Boolean

Returns true if the current severity level allows for sending DEBUG messages.

Returns:

  • (Boolean) 


314
315
316
 
# File 'lib/google/cloud/logging/logger.rb', line 314

def debug?
  @level <= 0
end

#delete_request_info ⇒ RequestInfo Also known as: delete_trace_id

Untrack the RequestInfo that's associated with current Thread

Returns:



447
448
449
 
# File 'lib/google/cloud/logging/logger.rb', line 447

def delete_request_info
  @request_info.delete current_thread_id
end

#error(message = nil) { ... } ⇒ Object

Log an ERROR entry.

Parameters:

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

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer).

Yields:

  • Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.



224
225
226
227
228
229
230
 
# File 'lib/google/cloud/logging/logger.rb', line 224

def error message = nil, &block
  if block_given?
    add 3, nil, message, &block
  else
    add 3, message, nil, &block
  end
end

#error? ⇒ Boolean

Returns true if the current severity level allows for sending ERROR messages.

Returns:

  • (Boolean) 


335
336
337
 
# File 'lib/google/cloud/logging/logger.rb', line 335

def error?
  @level <= 3
end

#fatal(message = nil) { ... } ⇒ Object

Log a FATAL entry.

Parameters:

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

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer).

Yields:

  • Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.



242
243
244
245
246
247
248
 
# File 'lib/google/cloud/logging/logger.rb', line 242

def fatal message = nil, &block
  if block_given?
    add 4, nil, message, &block
  else
    add 4, message, nil, &block
  end
end

#fatal? ⇒ Boolean

Returns true if the current severity level allows for sending FATAL messages.

Returns:

  • (Boolean) 


342
343
344
 
# File 'lib/google/cloud/logging/logger.rb', line 342

def fatal?
  @level <= 4
end

#info(message = nil) { ... } ⇒ Object

Log an INFO entry.

Parameters:

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

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer).

Yields:

  • Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.



188
189
190
191
192
193
194
 
# File 'lib/google/cloud/logging/logger.rb', line 188

def info message = nil, &block
  if block_given?
    add 1, nil, message, &block
  else
    add 1, message, nil, &block
  end
end

#info? ⇒ Boolean

Returns true if the current severity level allows for sending INFO messages.

Returns:

  • (Boolean) 


321
322
323
 
# File 'lib/google/cloud/logging/logger.rb', line 321

def info?
  @level <= 1
end

#progname=(name) ⇒ Object

This logger treats progname as an alias for log_name.



92
93
94
 
# File 'lib/google/cloud/logging/logger.rb', line 92

def progname= name
  @log_name = name
end

#reopen(_logdev = nil) ⇒ Object

Re-enable logging if the logger has been closed.

Note that this method accepts a "logdev" argument for compatibility with the standard Ruby Logger class; however, this argument is ignored because this logger does not use a log device.



390
391
392
393
 
# File 'lib/google/cloud/logging/logger.rb', line 390

def reopen _logdev = nil
  @closed = false
  self
end

#request_info ⇒ RequestInfo?

Get the request data for the current Thread

Returns:

  • (RequestInfo, nil) —

    The request data for the current thread, or nil if there is no data set.



438
439
440
 
# File 'lib/google/cloud/logging/logger.rb', line 438

def request_info
  @request_info[current_thread_id]
end

#trace_ids ⇒ Object

Deprecated.

Use request_info

A Hash of Thread IDs to Stackdriver request trace ID. The Stackdriver trace ID is a shared request identifier across all Stackdriver services.



103
104
105
 
# File 'lib/google/cloud/logging/logger.rb', line 103

def trace_ids
  @request_info.inject({}) { |r, (k, v)| r[k] = v.trace_id }
end

#unknown(message = nil) { ... } ⇒ Object

Log an UNKNOWN entry. This will be printed no matter what the logger's current severity level is.

Parameters:

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

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer).

Yields:

  • Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.



261
262
263
264
265
266
267
 
# File 'lib/google/cloud/logging/logger.rb', line 261

def unknown message = nil, &block
  if block_given?
    add 5, nil, message, &block
  else
    add 5, message, nil, &block
  end
end

#warn(message = nil) { ... } ⇒ Object

Log a WARN entry.

Parameters:

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

    The log entry payload, represented as either a string, a hash (JSON), or a hash (protocol buffer).

Yields:

  • Evaluates to the message to log. This is not evaluated unless the logger's level is sufficient to log the message. This allows you to create potentially expensive logging messages that are only called when the logger is configured to show them.



206
207
208
209
210
211
212
 
# File 'lib/google/cloud/logging/logger.rb', line 206

def warn message = nil, &block
  if block_given?
    add 2, nil, message, &block
  else
    add 2, message, nil, &block
  end
end

#warn? ⇒ Boolean

Returns true if the current severity level allows for sending WARN messages.

Returns:

  • (Boolean) 


328
329
330
 
# File 'lib/google/cloud/logging/logger.rb', line 328

def warn?
  @level <= 2
end