Class: Google::Cloud::Logging::AsyncWriter

Inherits:
Object
  • Object
show all
Includes:
Stackdriver::Core::AsyncActor
Defined in:
lib/google/cloud/logging/async_writer.rb

Overview

AsyncWriter

An object that batches and transmits log entries asynchronously.

Use this object to transmit log entries efficiently. It keeps a queue of log entries, and runs a background thread that transmits them to the logging service in batches. Generally, adding to the queue will not block.

This object is thread-safe; it may accept write requests from multiple threads simultaneously, and will serialize them when executing in the background thread.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

async = logging.async_writer

entry1 = logging.entry payload: "Job started."
entry2 = logging.entry payload: "Job completed."

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

async.write_entries [entry1, entry2],
                    log_name: "my_app_log",
                    resource: resource,
                    labels: labels

Constant Summary collapse

DEFAULT_MAX_QUEUE_SIZE = 
10000
CLEANUP_TIMEOUT = 
Stackdriver::Core::AsyncActor::CLEANUP_TIMEOUT
WAIT_INTERVAL = 
Stackdriver::Core::AsyncActor::WAIT_INTERVAL

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#last_exception ⇒ Object (readonly)

The last exception thrown by the background thread, or nil if nothing has been thrown.



95
96
97
 
# File 'lib/google/cloud/logging/async_writer.rb', line 95

def last_exception
  @last_exception
end

Instance Method Details

#logger(log_name, resource, labels = {}) ⇒ Google::Cloud::Logging::Logger

Creates a logger instance that is API-compatible with Ruby's standard library Logger.

The logger will use AsyncWriter to transmit log entries on a background thread.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new

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

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

Parameters:

  • 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: {}) —

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

Returns:



199
200
201
 
# File 'lib/google/cloud/logging/async_writer.rb', line 199

def logger log_name, resource, labels = {}
  Logger.new self, log_name, resource, labels
end

#stop!(timeout, force: false) ⇒ Symbol

Stop this asynchronous writer and block until it has been stopped.

DEPRECATED. Use #async_stop! instead.

Parameters:

  • timeout (Number) —

    Timeout in seconds.

  • force (Boolean) (defaults to: false) —

    If set to true, and the writer hasn't stopped within the given timeout, kill it forcibly by terminating the thread. This should be used with extreme caution, as it can leave RPCs unfinished. Default is false.

Returns:

  • (Symbol) —

    Returns :stopped if the AsyncWriter was already stopped at the time of invocation, :waited if it stopped during the timeout period, :timeout if it is still running after the timeout, or :forced if it was forcibly killed.



311
312
313
314
315
316
 
# File 'lib/google/cloud/logging/async_writer.rb', line 311

def stop! timeout, force: false
  @cleanup_options[:timeout] = timeout unless timeout.nil?
  @cleanup_options[:force] = force unless force.nil?

  async_stop!
end

#write_entries(entries, log_name: nil, resource: nil, labels: nil) ⇒ Google::Cloud::Logging::AsyncWriter

Asynchronously write one or more log entries to the Stackdriver Logging service.

Unlike the main write_entries method, this method usually does not block. The actual write RPCs will happen in the background, and may be batched with related calls. However, if the queue is full, this method will block until enough space has cleared out.

Examples:

require "google/cloud/logging"

logging = Google::Cloud::Logging.new
async = logging.async_writer

entry = logging.entry payload: "Job started.",
                      log_name: "my_app_log"
entry.resource.type = "gae_app"
entry.resource.labels[:module_id] = "1"
entry.resource.labels[:version_id] = "20150925t173233"

async.write_entries entry

Parameters:

  • entries (Google::Cloud::Logging::Entry, Array<Google::Cloud::Logging::Entry>) —

    One or more entry objects to write. The log entries must have values for all required fields.

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

    A default log ID for those log entries in entries that do not specify their own log_name. See also Entry#log_name=.

  • resource (Resource) (defaults to: nil) —

    A default monitored resource for those log entries in entries that do not specify their own resource. See also Entry#resource.

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

    User-defined key:value items that are added to the labels field of each log entry in entries, except when a log entry specifies its own key:value item with the same key. See also Entry#labels=.

Returns:



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/google/cloud/logging/async_writer.rb', line 151

def write_entries entries, log_name: nil, resource: nil, labels: nil
  ensure_thread
  entries = Array(entries)
  synchronize do
    raise "AsyncWriter has been stopped" unless writable?
    queue_item = QueueItem.new entries, log_name, resource, labels
    if @queue.empty? || !@queue.last.try_combine(queue_item)
      @queue.push queue_item
    end
    @queue_size += entries.size
    @queue_resource.broadcast
    while @max_queue_size && @queue_size > @max_queue_size
      @queue_resource.wait
    end
  end
  self
end