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

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

Overview

Logger

A (mostly) API-compatible logger for ruby's Logger.

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

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.



98
99
100
101
102
103
104
105
 
# File 'lib/google/cloud/logging/logger.rb', line 98

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
  @trace_ids = OrderedHash.new
end

Instance Attribute Details

#labels ⇒ Object (readonly)

The Google Cloud labels to write the log entry with.



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

def labels
  @labels
end

#log_name ⇒ Object (readonly)

The Google Cloud log_name to write the log entry with.



46
47
48
 
# File 'lib/google/cloud/logging/logger.rb', line 46

def log_name
  @log_name
end

#resource ⇒ Object (readonly)

The Google Cloud resource to write the log entry with.



50
51
52
 
# File 'lib/google/cloud/logging/logger.rb', line 50

def resource
  @resource
end

#trace_ids ⇒ Object (readonly)

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



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

def trace_ids
  @trace_ids
end

#writer ⇒ Object (readonly)

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



42
43
44
 
# File 'lib/google/cloud/logging/logger.rb', line 42

def writer
  @writer
end

Instance Method Details

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



230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
 
# File 'lib/google/cloud/logging/logger.rb', line 230

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
end

#add_trace_id(trace_id) ⇒ Object

Track a given trace_id by associating it with the current Thread

Parameters:

  • trace_id (String) —

    The HTTP_X_CLOUD_TRACE_CONTEXT HTTP request header that's shared and tracked by all Stackdriver services



315
316
317
318
319
320
321
322
 
# File 'lib/google/cloud/logging/logger.rb', line 315

def add_trace_id trace_id
  trace_ids[current_thread_id] = trace_id

  # Start removing old entries if hash gets too large.
  # This should never happen, because middleware should automatically
  # remove entries when a request is finished
  trace_ids.shift if trace_ids.size > 10_000
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.



117
118
119
120
121
122
123
 
# File 'lib/google/cloud/logging/logger.rb', line 117

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) 


250
251
252
 
# File 'lib/google/cloud/logging/logger.rb', line 250

def debug?
  @level <= 0
end

#delete_trace_id ⇒ Object

Untrack the trace_id that's associated with current Thread

Returns:

  • The trace_id that's being deleted



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

def delete_trace_id
  trace_ids.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.



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

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) 


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

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.



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

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) 


278
279
280
 
# File 'lib/google/cloud/logging/logger.rb', line 278

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.



135
136
137
138
139
140
141
 
# File 'lib/google/cloud/logging/logger.rb', line 135

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) 


257
258
259
 
# File 'lib/google/cloud/logging/logger.rb', line 257

def info?
  @level <= 1
end

#level=(severity) ⇒ Object Also known as: sev_threshold=

Sets the logging severity level.

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.level = "INFO"
logger.debug "Job started." # No log entry written

Parameters:

  • severity (Integer, String, Symbol) —

    the integer code for or the name of the severity level



302
303
304
305
306
 
# File 'lib/google/cloud/logging/logger.rb', line 302

def level= severity
  new_level = derive_severity severity
  fail ArgumentError, "invalid log level: #{severity}" if new_level.nil?
  @level = new_level
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.



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

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.



153
154
155
156
157
158
159
 
# File 'lib/google/cloud/logging/logger.rb', line 153

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) 


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

def warn?
  @level <= 2
end