google-cloud-logging 0.20.1 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aa3ebfa38e22e40778bd4a67a5d0f6373fd094a4
-  data.tar.gz: a792bb01d9ba78eb0c728771eb07528280170bf0
+  metadata.gz: 8c9421790cb4f209636fe57644a348a9076ed293
+  data.tar.gz: 79e077faf17e8a77e8f4a471a3421207743d826c
 SHA512:
-  metadata.gz: 4f751572455011147d48324f1159fa9d18ce447eb2bfa69bc8a150906386eaad5f033f4b8167da7d7cf84fcc1691bd3af2f04e82fa251abb194ce18e3b94a55b
-  data.tar.gz: e8fc4fe86dc494fc4e3f1e2ea951f14fd6941a132394b8c26a1eddf620f6946da00832e1cd7556eed81aa5fe9fbe4f1fc5ab08b8ec34dc4e2cd6c8397731a70a
+  metadata.gz: 6d797aa5a7888d7b6f617439f37e8b20695fd4ac8c5b2f241ac52376bfdcf5154c2faf268e3411c09697d4ee37d13f3abe2f7428b5650ce7db3cdc581fae4eaf
+  data.tar.gz: 9c6ec7fe172ac640ebaa6c94c0501ed0e90b3b8004ba2387de6aadbaafcb134500a7d7ebf6a9aa921afa181ff663b48aa79d6271d2da86fdac2942d2cfbe1fc9

data/lib/google-cloud-logging.rb

@@ -13,8 +13,8 @@
 # limitations under the License.
 
 ##
-# This file is here to be autorequired by bundler, so that the .bigquery and
-# #bigquery methods can be available, but the library and all dependencies won't
+# This file is here to be autorequired by bundler, so that the .logging and
+# #logging methods can be available, but the library and all dependencies won't
 # be loaded until required and used.
 
 
@@ -38,9 +38,9 @@ module Google
     #   The default scope is:
     #
     #   * `https://www.googleapis.com/auth/logging.admin`
-    # @param [Integer] retries Number of times to retry requests on server
-    #   error. The default value is `3`. Optional.
     # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [Hash] client_config A hash of values to override the default
+    #   behavior of the API client. Optional.
     #
     # @return [Google::Cloud::Logging::Project]
     #
@@ -49,7 +49,11 @@ module Google
     #
     #   gcloud = Google::Cloud.new
     #   logging = gcloud.logging
-    #   # ...
+    #
+    #   entries = logging.entries
+    #   entries.each do |e|
+    #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+    #   end
     #
     # @example The default scope can be overridden with the `scope` option:
     #   require "google/cloud"
@@ -58,10 +62,10 @@ module Google
     #   platform_scope = "https://www.googleapis.com/auth/cloud-platform"
     #   logging = gcloud.logging scope: platform_scope
     #
-    def logging scope: nil, retries: nil, timeout: nil
+    def logging scope: nil, timeout: nil, client_config: nil
       Google::Cloud.logging @project, @keyfile, scope: scope,
-                                                retries: (retries || @retries),
-                                                timeout: (timeout || @timeout)
+                                                timeout: (timeout || @timeout),
+                                                client_config: client_config
     end
 
     ##
@@ -72,7 +76,7 @@ module Google
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
     # @param [String] project Project identifier for the Stackdriver Logging
-    #   service.
+    #   service you are connecting to.
     # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
     #   file path the file must be readable.
     # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
@@ -83,37 +87,28 @@ module Google
     #   The default scope is:
     #
     #   * `https://www.googleapis.com/auth/logging.admin`
-    # @param [Integer] retries Number of times to retry requests on server
-    #   error. The default value is `3`. Optional.
     # @param [Integer] timeout Default timeout to use in requests. Optional.
+    # @param [Hash] client_config A hash of values to override the default
+    #   behavior of the API client. Optional.
     #
     # @return [Google::Cloud::Logging::Project]
     #
     # @example
-    #   require "google/cloud/logging"
+    #   require "google/cloud"
     #
-    #   gcloud = Google::Cloud.new
-    #   logging = gcloud.logging
-    #   # ...
+    #   logging = Google::Cloud.logging
     #
-    def self.logging project = nil, keyfile = nil, scope: nil, retries: nil,
-                     timeout: nil
+    #   entries = logging.entries
+    #   entries.each do |e|
+    #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+    #   end
+    #
+    def self.logging project = nil, keyfile = nil, scope: nil, timeout: nil,
+                     client_config: nil
       require "google/cloud/logging"
-      project ||= Google::Cloud::Logging::Project.default_project
-      project = project.to_s # Always cast to a string
-      fail ArgumentError, "project is missing" if project.empty?
-
-      if keyfile.nil?
-        credentials = Google::Cloud::Logging::Credentials.default(
-          scope: scope)
-      else
-        credentials = Google::Cloud::Logging::Credentials.new(
-          keyfile, scope: scope)
-      end
-
-      Google::Cloud::Logging::Project.new(
-        Google::Cloud::Logging::Service.new(
-          project, credentials, retries: retries, timeout: timeout))
+      Google::Cloud::Logging.new project: project, keyfile: keyfile,
+                                 scope: scope, timeout: timeout,
+                                 client_config: client_config
     end
   end
 end

data/lib/google/cloud/logging.rb

@@ -44,6 +44,11 @@ module Google
     # about the options for connecting in the [Authentication
     # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
     #
+    # If you just want to write your application's logs to the Stackdriver
+    # Logging service, you may find it easiest to use the [Ruby Logger
+    # implementation](#creating-a-ruby-logger-implementation) provided by this
+    # library. Otherwise, read on to learn more about the Logging API.
+    #
     # ## Listing log entries
     #
     # Stackdriver Logging gathers log entries from many services, including
@@ -55,10 +60,9 @@ module Google
     # {Google::Cloud::Logging::Entry} records belonging to your project:
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     # entries = logging.entries
     # entries.each do |e|
     #   puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
@@ -75,10 +79,9 @@ module Google
     # Stackdriver Logging API.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     # entries = logging.entries filter: "log:syslog"
     # entries.each do |e|
     #   puts "[#{e.timestamp}] #{e.payload.inspect}"
@@ -88,10 +91,9 @@ module Google
     # You can also order the log entries by `timestamp`.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     # entries = logging.entries order: "timestamp desc"
     # entries.each do |e|
     #   puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
@@ -121,11 +123,9 @@ module Google
     # logs](https://cloud.google.com/logging/docs/export/configure_export#setting_product_name_short_permissions_for_writing_exported_logs).
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
-    # storage = gcloud.storage
+    # storage = Google::Cloud::Storage.new
     #
     # bucket = storage.create_bucket "my-logs-bucket"
     #
@@ -133,6 +133,10 @@ module Google
     # email = "cloud-logs@google.com"
     # bucket.acl.add_owner "group-#{email}"
     #
+    # require "google/cloud/logging"
+    #
+    # logging = Google::Cloud::Logging.new
+    #
     # sink = logging.create_sink "my-sink",
     #                            "storage.googleapis.com/#{bucket.id}"
     # ```
@@ -147,10 +151,9 @@ module Google
     # {Google::Cloud::Logging::Project#sinks}.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     # sinks = logging.sinks
     # sinks.each do |s|
     #   puts "#{s.name}: #{s.filter} -> #{s.destination}"
@@ -172,10 +175,9 @@ module Google
     # filter](https://cloud.google.com/logging/docs/view/advanced_filters).
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     # metric = logging.create_metric "errors", "severity>=ERROR"
     # ```
     #
@@ -185,10 +187,9 @@ module Google
     # {Google::Cloud::Logging::Project#metrics}.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     # metrics = logging.metrics
     # metrics.each do |m|
     #   puts "#{m.name}: #{m.filter}"
@@ -205,10 +206,9 @@ module Google
     # contain a log name and a resource.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     #
     # entry = logging.entry
     # entry.payload = "Job started."
@@ -225,10 +225,9 @@ module Google
     # these values from the individual entries.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     #
     # entry1 = logging.entry
     # entry1.payload = "Job started."
@@ -246,6 +245,36 @@ module Google
     #                       labels: labels
     # ```
     #
+    # Normally, writing log entries is done synchronously; the call to
+    # {Google::Cloud::Logging::Project#write_entries} will block until it has
+    # either completed transmitting the data or encountered an error. To "fire
+    # and forget" without blocking, use {Google::Cloud::Logging::AsyncWriter};
+    # it spins up a background thread that writes log entries in batches. Calls
+    # to {Google::Cloud::Logging::AsyncWriter#write_entries} simply add entries
+    # to its work queue and return immediately.
+    #
+    # ```ruby
+    # require "google/cloud/logging"
+    #
+    # logging = Google::Cloud::Logging.new
+    # async = logging.async_writer
+    #
+    # entry1 = logging.entry
+    # entry1.payload = "Job started."
+    # entry2 = logging.entry
+    # entry2.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
+    # ```
+    #
     # ### Creating a Ruby Logger implementation
     #
     # If your environment requires a logger instance that is API-compatible with
@@ -254,10 +283,9 @@ module Google
     # {Google::Cloud::Logging::Project#logger} to create one.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging
+    # logging = Google::Cloud::Logging.new
     #
     # resource = logging.resource "gae_app",
     #                             module_id: "1",
@@ -267,27 +295,89 @@ module Google
     # logger.info "Job started."
     # ```
     #
-    # ## Configuring retries and timeout
+    # By default, the logger instance writes log entries asynchronously in a
+    # background thread using an {Google::Cloud::Logging::AsyncWriter}. If you
+    # want to customize or disable asynchronous writing, you may call the
+    # Logger constructor directly.
     #
-    # You can configure how many times API requests may be automatically
-    # retried. When an API request fails, the response will be inspected to see
-    # if the request meets criteria indicating that it may succeed on retry,
-    # such as `500` and `503` status codes or a specific internal error code
-    # such as `rateLimitExceeded`. If it meets the criteria, the request will be
-    # retried after a delay. If another error occurs, the delay will be
-    # increased before a subsequent attempt, until the `retries` limit is
-    # reached.
+    # ```ruby
+    # require "google/cloud/logging"
     #
-    # You can also set the request `timeout` value in seconds.
+    # logging = Google::Cloud::Logging.new
+    #
+    # resource = logging.resource "gae_app",
+    #                             module_id: "1",
+    #                             version_id: "20150925t173233"
+    #
+    # logger = Google::Cloud::Logging::Logger.new logging,
+    #                                             "my_app_log",
+    #                                             resource,
+    #                                             {env: :production}
+    # logger.info "Log entry written synchronously."
+    # ```
+    #
+    # ## Configuring timeout
+    #
+    # You can configure the request `timeout` value in seconds.
     #
     # ```ruby
-    # require "google/cloud"
+    # require "google/cloud/logging"
     #
-    # gcloud = Google::Cloud.new
-    # logging = gcloud.logging retries: 10, timeout: 120
+    # logging = Google::Cloud::Logging.new timeout: 120
     # ```
     #
     module Logging
+      ##
+      # Creates a new object for connecting to the Stackdriver Logging service.
+      # Each call creates a new connection.
+      #
+      # For more information on connecting to Google Cloud see the
+      # [Authentication
+      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
+      #
+      # @param [String] project Project identifier for the Stackdriver Logging
+      #   service.
+      # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
+      #   file path the file must be readable.
+      # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling
+      #   the set of resources and operations that the connection can access.
+      #   See [Using OAuth 2.0 to Access Google
+      #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+      #
+      #   The default scope is:
+      #
+      #   * `https://www.googleapis.com/auth/logging.admin`
+      # @param [Integer] timeout Default timeout to use in requests. Optional.
+      # @param [Hash] client_config A hash of values to override the default
+      #   behavior of the API client. Optional.
+      #
+      # @return [Google::Cloud::Logging::Project]
+      #
+      # @example
+      #   require "google/cloud/logging"
+      #
+      #   logging = Google::Cloud::Logging.new
+      #
+      #   entries = logging.entries
+      #   entries.each do |e|
+      #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+      #   end
+      #
+      def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
+                   client_config: nil
+        project ||= Google::Cloud::Logging::Project.default_project
+        project = project.to_s # Always cast to a string
+        fail ArgumentError, "project is missing" if project.empty?
+
+        credentials =
+          Google::Cloud::Logging::Credentials.credentials_with_scope keyfile,
+                                                                     scope
+
+        Google::Cloud::Logging::Project.new(
+          Google::Cloud::Logging::Service.new(
+            project, credentials, timeout: timeout,
+                                  client_config: client_config))
+      end
     end
   end
 end

data/lib/google/cloud/logging/async_writer.rb

@@ -0,0 +1,399 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Logging
+      ##
+      # # 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.
+      #
+      # @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
+      #
+      class AsyncWriter
+        DEFAULT_MAX_QUEUE_SIZE = 10000
+
+        ##
+        # @private Item in the log entries queue.
+        QueueItem = Struct.new(:entries, :log_name, :resource, :labels) do
+          def try_combine next_item
+            if log_name == next_item.log_name &&
+               resource == next_item.resource &&
+               labels == next_item.labels
+              entries.concat(next_item.entries)
+              true
+            else
+              false
+            end
+          end
+        end
+
+        ##
+        # @private The logging object.
+        attr_accessor :logging
+
+        ##
+        # @private The maximum size of the entries queue, or nil if not set.
+        attr_accessor :max_queue_size
+
+        ##
+        # The current state. Either :running, :suspended, :stopping, or :stopped
+        attr_reader :state
+
+        ##
+        # The last exception thrown by the background thread, or nil if nothing
+        # has been thrown.
+        attr_reader :last_exception
+
+        ##
+        # @private Creates a new AsyncWriter instance.
+        def initialize logging, max_queue_size = DEFAULT_MAX_QUEUE_SIZE
+          @logging = logging
+          @max_queue_size = max_queue_size
+          @startup_lock = Mutex.new
+          @thread = nil
+          @state = :running
+        end
+
+        ##
+        # 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.
+        #
+        # @param [Google::Cloud::Logging::Entry,
+        #   Array<Google::Cloud::Logging::Entry>] entries One or more entry
+        #   objects to write. The log entries must have values for all required
+        #   fields.
+        # @param [String] log_name A default log ID for those log entries in
+        #   `entries` that do not specify their own `log_name`. See also
+        #   {Entry#log_name=}.
+        # @param [Resource] resource A default monitored resource for those log
+        #   entries in entries that do not specify their own resource. See also
+        #   {Entry#resource}.
+        # @param [Hash{Symbol,String => String}] labels 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=}.
+        #
+        # @return [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
+        #
+        def write_entries entries, log_name: nil, resource: nil, labels: nil
+          ensure_thread
+          entries = Array(entries)
+          @lock.synchronize do
+            fail "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
+            @lock_cond.broadcast
+            while @max_queue_size && @queue_size > @max_queue_size
+              @lock_cond.wait
+            end
+          end
+          self
+        end
+
+        ##
+        # Creates a logger instance that is API-compatible with Ruby's standard
+        # library [Logger](http://ruby-doc.org/stdlib/libdoc/logger/rdoc).
+        #
+        # The logger will use AsyncWriter to transmit log entries on a
+        # background thread.
+        #
+        # @param [String] log_name A log resource name to be associated with the
+        #   written log entries.
+        # @param [Google::Cloud::Logging::Resource] resource The monitored
+        #   resource to be associated with written log entries.
+        # @param [Hash] labels A set of user-defined data to be associated with
+        #   written log entries.
+        #
+        # @return [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."
+        #
+        def logger log_name, resource, labels = {}
+          Logger.new self, log_name, resource, labels
+        end
+
+        ##
+        # Stops this asynchronous writer.
+        #
+        # After this call succeeds, the state will change to :stopping, and
+        # you may not issue any additional write_entries calls. Any previously
+        # issued writes will complete. Once any existing backlog has been
+        # cleared, the state will change to :stopped.
+        #
+        # @return [Boolean] Returns true if the writer was running, or false
+        #   if the writer had already been stopped.
+        #
+        def stop
+          ensure_thread
+          @lock.synchronize do
+            if state != :stopped
+              @state = :stopping
+              @lock_cond.broadcast
+              true
+            else
+              false
+            end
+          end
+        end
+
+        ##
+        # Suspends this asynchronous writer.
+        #
+        # After this call succeeds, the state will change to :suspended, and
+        # the writer will stop sending RPCs until resumed.
+        #
+        # @return [Boolean] Returns true if the writer had been running and was
+        #   suspended, otherwise false.
+        #
+        def suspend
+          ensure_thread
+          @lock.synchronize do
+            if state == :running
+              @state = :suspended
+              @lock_cond.broadcast
+              true
+            else
+              false
+            end
+          end
+        end
+
+        ##
+        # Resumes this suspended asynchronous writer.
+        #
+        # After this call succeeds, the state will change to :running, and
+        # the writer will resume sending RPCs.
+        #
+        # @return [Boolean] Returns true if the writer had been suspended and
+        #   is now running, otherwise false.
+        #
+        def resume
+          ensure_thread
+          @lock.synchronize do
+            if state == :suspended
+              @state = :running
+              @lock_cond.broadcast
+              true
+            else
+              false
+            end
+          end
+        end
+
+        ##
+        # Returns true if this writer is running.
+        #
+        # @return [Boolean] Returns true if the writer is currently running.
+        #
+        def running?
+          ensure_thread
+          @lock.synchronize do
+            state == :running
+          end
+        end
+
+        ##
+        # Returns true if this writer is suspended.
+        #
+        # @return [Boolean] Returns true if the writer is currently suspended.
+        #
+        def suspended?
+          ensure_thread
+          @lock.synchronize do
+            state == :suspended
+          end
+        end
+
+        ##
+        # Returns true if this writer is still accepting writes. This means
+        # it is either running or suspended.
+        #
+        # @return [Boolean] Returns true if the writer is accepting writes.
+        #
+        def writable?
+          ensure_thread
+          @lock.synchronize do
+            state == :suspended || state == :running
+          end
+        end
+
+        ##
+        # Returns true if this writer is fully stopped.
+        #
+        # @return [Boolean] Returns true if the writer is fully stopped.
+        #
+        def stopped?
+          ensure_thread
+          @lock.synchronize do
+            state == :stopped
+          end
+        end
+
+        ##
+        # Blocks until this asynchronous writer has been stopped, or the given
+        # timeout (if present) has elapsed.
+        #
+        # @param [Number] timeout Timeout in seconds, or nil for no timeout.
+        #
+        # @return [Boolean] Returns true if the writer is stopped, or false
+        #   if the timeout expired.
+        #
+        def wait_until_stopped timeout = nil
+          ensure_thread
+          deadline = timeout ? ::Time.new.to_f + timeout : nil
+          @lock.synchronize do
+            until state == :stopped
+              cur_time = ::Time.new.to_f
+              return false if deadline && cur_time >= deadline
+              @lock_cond.wait(deadline ? deadline - cur_time : nil)
+            end
+          end
+          true
+        end
+
+        protected
+
+        ##
+        # @private Ensures the background thread is running. This is called
+        # at the start of all public methods, and kicks off the thread lazily.
+        # It also ensures the thread gets restarted (with an empty queue) in
+        # case this object is forked into a child process.
+        #
+        def ensure_thread
+          @startup_lock.synchronize do
+            if (@thread.nil? || !@thread.alive?) && @state != :stopped
+              @queue_size = 0
+              @queue = []
+              @lock = Monitor.new
+              @lock_cond = @lock.new_cond
+              @thread = Thread.new { run_backgrounder }
+            end
+          end
+        end
+
+        ##
+        # @private The background thread implementation, which continuously
+        # waits for performs work, and returns only when fully stopped.
+        #
+        def run_backgrounder
+          loop do
+            queue_item = wait_next_item
+            return unless queue_item
+            begin
+              logging.write_entries(
+                queue_item.entries,
+                log_name: queue_item.log_name,
+                resource: queue_item.resource,
+                labels: queue_item.labels
+              )
+            rescue => e
+              # Ignore any exceptions thrown from the background thread, but
+              # keep running to ensure its state behavior remains consistent.
+              @last_exception = e
+            end
+          end
+        end
+
+        ##
+        # @private Wait for and dequeue the next set of log entries to transmit.
+        #
+        # @return [QueueItem,NilClass] Returns the next set of entries. If
+        #   the writer has been stopped and no more entries are left in the
+        #   queue, returns nil.
+        #
+        def wait_next_item
+          @lock.synchronize do
+            while state == :suspended ||
+                  (state == :running && @queue.empty?)
+              @lock_cond.wait
+            end
+            if @queue.empty?
+              @state = :stopped
+              nil
+            else
+              queue_item = @queue.shift
+              @queue_size -= queue_item.entries.size
+              @lock_cond.broadcast
+              queue_item
+            end
+          end
+        end
+      end
+    end
+  end
+end