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

Provide a hash to write a JSON payload to the log:

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

payload = { "stats" => { "a" => 8, "b" => 12.5} }
logger.info payload

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.



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/google/cloud/logging/logger.rb', line 169

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_var = Concurrent::ThreadLocalVar.new
  @closed = false
  # Unused, but present for API compatibility
  @formatter = ::Logger::Formatter.new
  @datetime_format = ""
  @silencer = true

  # 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.



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

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.



99
100
101
 
# File 'lib/google/cloud/logging/logger.rb', line 99

def formatter
  @formatter
end

#labels ⇒ Object (readonly)

The Google Cloud labels to write the log entry with.



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

def labels
  @labels
end

#level ⇒ Object Also known as: sev_threshold, local_level

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



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

def level
  @level
end

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

The Google Cloud log_name to write the log entry with.



74
75
76
 
# File 'lib/google/cloud/logging/logger.rb', line 74

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.



109
110
111
 
# File 'lib/google/cloud/logging/logger.rb', line 109

def project
  @project
end

#resource ⇒ Object (readonly)

The Google Cloud resource to write the log entry with.



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

def resource
  @resource
end

#silencer ⇒ Object

Boolean flag that indicates whether this logger can be silenced or not.



94
95
96
 
# File 'lib/google/cloud/logging/logger.rb', line 94

def silencer
  @silencer
end

#writer ⇒ Object (readonly)

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



70
71
72
 
# File 'lib/google/cloud/logging/logger.rb', line 70

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.



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

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.



310
311
312
313
314
315
316
317
318
319
320
321
 
# File 'lib/google/cloud/logging/logger.rb', line 310

def add severity, message = nil, progname = nil
  return if @closed

  severity = derive_severity(severity) || ::Logger::UNKNOWN
  return true if severity < @level

  message ||= block_given? ? yield : progname
  # TODO: Figure out what to do with the progname

  write_entry severity, message unless @closed
  true
end

#add_request_info(info: nil, env: nil, trace_id: nil, log_name: nil, trace_sampled: 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) (defaults to: nil) —

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

  • trace_id (String, nil) (defaults to: nil) —

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

  • log_name (String, nil) (defaults to: nil) —

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

  • env (Hash, nil) (defaults to: nil) —

    The request's Rack environment or nil if not available.



453
454
455
456
457
458
459
460
 
# File 'lib/google/cloud/logging/logger.rb', line 453

def add_request_info info: nil, env: nil, trace_id: nil, log_name: nil,
                     trace_sampled: nil
  info ||= RequestInfo.new trace_id, log_name, env, trace_sampled

  @request_info_var.value = info

  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



434
435
436
 
# File 'lib/google/cloud/logging/logger.rb', line 434

def add_trace_id trace_id
  add_request_info 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.



411
412
413
414
 
# File 'lib/google/cloud/logging/logger.rb', line 411

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.



197
198
199
200
201
202
203
 
# File 'lib/google/cloud/logging/logger.rb', line 197

def debug message = nil, &block
  if block_given?
    add ::Logger::DEBUG, nil, message, &block
  else
    add ::Logger::DEBUG, message
  end
end

#debug? ⇒ Boolean

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

Returns:

  • (Boolean) 


337
338
339
 
# File 'lib/google/cloud/logging/logger.rb', line 337

def debug?
  @level <= ::Logger::DEBUG
end

#delete_request_info ⇒ RequestInfo Also known as: delete_trace_id

Untrack the RequestInfo that's associated with current Thread

Returns:



477
478
479
 
# File 'lib/google/cloud/logging/logger.rb', line 477

def delete_request_info
  @request_info_var.value = nil
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.



251
252
253
254
255
256
257
 
# File 'lib/google/cloud/logging/logger.rb', line 251

def error message = nil, &block
  if block_given?
    add ::Logger::ERROR, nil, message, &block
  else
    add ::Logger::ERROR, message
  end
end

#error? ⇒ Boolean

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

Returns:

  • (Boolean) 


358
359
360
 
# File 'lib/google/cloud/logging/logger.rb', line 358

def error?
  @level <= ::Logger::ERROR
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.



269
270
271
272
273
274
275
 
# File 'lib/google/cloud/logging/logger.rb', line 269

def fatal message = nil, &block
  if block_given?
    add ::Logger::FATAL, nil, message, &block
  else
    add ::Logger::FATAL, message
  end
end

#fatal? ⇒ Boolean

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

Returns:

  • (Boolean) 


365
366
367
 
# File 'lib/google/cloud/logging/logger.rb', line 365

def fatal?
  @level <= ::Logger::FATAL
end

#flush ⇒ Object

No-op method. Created to match the spec of ActiveSupport::Logger#flush method when used in Rails application.



488
489
490
 
# File 'lib/google/cloud/logging/logger.rb', line 488

def flush
  self
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.



215
216
217
218
219
220
221
 
# File 'lib/google/cloud/logging/logger.rb', line 215

def info message = nil, &block
  if block_given?
    add ::Logger::INFO, nil, message, &block
  else
    add ::Logger::INFO, message
  end
end

#info? ⇒ Boolean

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

Returns:

  • (Boolean) 


344
345
346
 
# File 'lib/google/cloud/logging/logger.rb', line 344

def info?
  @level <= ::Logger::INFO
end

#progname=(name) ⇒ Object

This logger treats progname as an alias for log_name.



113
114
115
 
# File 'lib/google/cloud/logging/logger.rb', line 113

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.



423
424
425
426
 
# File 'lib/google/cloud/logging/logger.rb', line 423

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.



468
469
470
 
# File 'lib/google/cloud/logging/logger.rb', line 468

def request_info
  @request_info_var.value
end

#silence(temp_level = ::Logger::ERROR) ⇒ Object

Filter out low severity messages within block.

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.silence do
  logger.info "Info message"   # No log entry written
  logger.error "Error message" # Log entry written
end

Parameters:

  • temp_level (Integer) (defaults to: ::Logger::ERROR) —

    Severity threshold to filter within the block. Messages with lower severity will be blocked. Default ::Logger::ERROR



514
515
516
517
518
519
520
521
522
523
524
525
526
527
 
# File 'lib/google/cloud/logging/logger.rb', line 514

def silence temp_level = ::Logger::ERROR
  if silencer
    begin
      old_level = level
      self.level = temp_level

      yield self
    ensure
      self.level = old_level
    end
  else
    yield self
  end
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.

This method is deprecated and returns a Hash containing only the current Thread ID/trace_id now.



127
128
129
130
131
 
# File 'lib/google/cloud/logging/logger.rb', line 127

def trace_ids
  current_request_info = request_info
  return {} if current_request_info.nil?
  { current_thread_id => current_request_info.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.



288
289
290
291
292
293
294
 
# File 'lib/google/cloud/logging/logger.rb', line 288

def unknown message = nil, &block
  if block_given?
    add ::Logger::UNKNOWN, nil, message, &block
  else
    add ::Logger::UNKNOWN, message
  end
end

#unknown? ⇒ Boolean

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

Returns:

  • (Boolean) 


372
373
374
 
# File 'lib/google/cloud/logging/logger.rb', line 372

def unknown?
  @level <= ::Logger::UNKNOWN
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.



233
234
235
236
237
238
239
 
# File 'lib/google/cloud/logging/logger.rb', line 233

def warn message = nil, &block
  if block_given?
    add ::Logger::WARN, nil, message, &block
  else
    add ::Logger::WARN, message
  end
end

#warn? ⇒ Boolean

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

Returns:

  • (Boolean) 


351
352
353
 
# File 'lib/google/cloud/logging/logger.rb', line 351

def warn?
  @level <= ::Logger::WARN
end