google-cloud-logging - Class Google::Cloud::Logging::AsyncWriter (v2.2.2)

Reference documentation and code samples for the google-cloud-logging class Google::Cloud::Logging::AsyncWriter.

AsyncWriter

AsyncWriter buffers, batches, and transmits log entries efficiently. Writing log entries is asynchronous and will not block.

Batches that cannot be delivered immediately are queued. When the queue is full new batch requests will raise errors that can be consumed using the #on_error callback. This provides back pressure in case the writer cannot keep up with requests.

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

Inherits

Object

Includes

MonitorMixin

Example

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

Methods

#async_stop!

def async_stop!(timeout = nil, force: nil) -> Symbol

Alias Of: #stop!

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

Parameters

timeout (Number, nil) — The maximum number of seconds to wait for shutdown to complete. Will wait forever when the value is nil. The default value is nil.
force (Boolean) (defaults to: nil) — 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 :new if #write_entries has never been called on the AsyncWriter, :stopped if it 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.

#flush

def flush() -> AsyncWriter

Forces all entries in the current batch to be published immediately.

Returns

(AsyncWriter) — returns self so calls can be chained.

#last_error

def last_error() -> Exception, nil

Aliases

#last_exception

The most recent unhandled error to occur while transmitting log entries.

If an unhandled error has occurred the subscriber will attempt to recover from the error and resume buffering, batching, and transmitting log entries.

Returns

(Exception, nil) — error The most recent error raised.

Example

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

# If an error was raised, it can be retrieved here:
async.last_error #=> nil

#last_exception

def last_exception() -> Exception, nil

Alias Of: #last_error

The most recent unhandled error to occur while transmitting log entries.

If an unhandled error has occurred the subscriber will attempt to recover from the error and resume buffering, batching, and transmitting log entries.

Returns

(Exception, nil) — error The most recent error raised.

Example

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

# If an error was raised, it can be retrieved here:
async.last_error #=> nil

#logger

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

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) — A set of user-defined data to be associated with written log entries.

Returns

(Google::Cloud::Logging::Logger) — a Logger object that can be used in place of a ruby standard library logger object.

Example

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

#on_error

def on_error(&block) { |error| ... }

If an unhandled error has occurred the writer will attempt to recover from the error and resume buffering, batching, and transmitting log entries

Multiple error handlers can be added.

Yields

(callback) — The block to be called when an error is raised.

Yield Parameter

error (Exception) — The error raised.

Example

require "google/cloud/logging"
require "google/cloud/error_reporting"

logging = Google::Cloud::Logging.new

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

async = logging.async_writer

# Register to be notified when unhandled errors occur.
async.on_error do |error|
  # error can be a AsyncWriterError or AsyncWriteEntriesError
  Google::Cloud::ErrorReporting.report error
end

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

#started?

def started?() -> boolean

Whether the writer has been started.

Returns

(boolean) — true when started, false otherwise.

#stop

def stop() -> AsyncWriter

Begins the process of stopping the writer. Entries already in the queue will be published, but no new entries can be added. Use #wait! to block until the writer is fully stopped and all pending entries have been published.

Returns

(AsyncWriter) — returns self so calls can be chained.

#stop!

def stop!(timeout = nil, force: nil) -> Symbol

Aliases

#async_stop!

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

Parameters

timeout (Number, nil) — The maximum number of seconds to wait for shutdown to complete. Will wait forever when the value is nil. The default value is nil.
force (Boolean) (defaults to: nil) — 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 :new if #write_entries has never been called on the AsyncWriter, :stopped if it 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.

#stopped?

def stopped?() -> boolean

Whether the writer has been stopped.

Returns

(boolean) — true when stopped, false otherwise.

#wait!

def wait!(timeout = nil) -> AsyncWriter

Blocks until the writer is fully stopped, all pending entries have been published, and all callbacks have completed. Does not stop the writer. To stop the writer, first call #stop and then call #wait! to block until the writer is stopped.

Parameter

timeout (Number, nil) — The maximum number of seconds to wait for shutdown to complete. Will wait forever when the value is nil. The default value is nil.

Returns

(AsyncWriter) — returns self so calls can be chained.

#write_entries

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

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

(Google::Cloud::Logging::AsyncWriter) — Returns self.

Example

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