google-cloud-logging 1.5.7 → 1.6.0

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

@@ -23,25 +23,31 @@ module Google
         # @private Convert a Hash to a Google::Protobuf::Struct.
         def self.hash_to_struct hash
           # TODO: ArgumentError if hash is not a Hash
-          Google::Protobuf::Struct.new fields:
-            Hash[hash.map { |k, v| [String(k), object_to_value(v)] }]
+          Google::Protobuf::Struct.new \
+            fields: Hash[hash.map { |k, v| [String(k), object_to_value(v)] }]
+        end
+
+        ##
+        # @private Convert an Array to a Google::Protobuf::ListValue.
+        def self.array_to_list array
+          # TODO: ArgumentError if array is not an Array
+          Google::Protobuf::ListValue.new \
+            values: array.map { |o| object_to_value(o) }
         end
 
         ##
         # @private Convert an Object to a Google::Protobuf::Value.
         def self.object_to_value obj
           case obj
-          when NilClass then Google::Protobuf::Value.new null_value:
-            :NULL_VALUE
+          when NilClass then Google::Protobuf::Value.new null_value: :NULL_VALUE
           when Numeric then Google::Protobuf::Value.new number_value: obj
           when String then Google::Protobuf::Value.new string_value: obj
           when TrueClass then Google::Protobuf::Value.new bool_value: true
           when FalseClass then Google::Protobuf::Value.new bool_value: false
-          when Hash then Google::Protobuf::Value.new struct_value:
-            hash_to_struct(obj)
-          when Array then Google::Protobuf::Value.new list_value:
-            Google::Protobuf::ListValue.new(values:
-              obj.map { |o| object_to_value(o) })
+          when Hash then
+            Google::Protobuf::Value.new struct_value: hash_to_struct(obj)
+          when Array then
+            Google::Protobuf::Value.new list_value: array_to_list(obj)
           else
             # TODO: Could raise ArgumentError here, or convert to a string
             Google::Protobuf::Value.new string_value: obj.to_s

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

@@ -71,6 +71,21 @@ module Google
       #   logging.write_entries entry
       #
       class Entry
+        ##
+        # Generate a pseudo-random, 16-character ID suitable for use as the log
+        # entry's {#insert_id}.
+        #
+        # @return [String]
+        #
+        # @example
+        #   require "google/cloud/logging"
+        #
+        #   insert_id = Google::Cloud::Logging::Entry.insert_id
+        #
+        def self.insert_id
+          rand(36**16).to_s 36
+        end
+
         ##
         # Create a new Entry instance. The {#resource} attribute is
         # pre-populated with a new {Google::Cloud::Logging::Resource} instance.
@@ -82,6 +97,7 @@ module Google
           @operation = Operation.new
           @severity = :DEFAULT
           @source_location = SourceLocation.new
+          @insert_id = Entry.insert_id
         end
 
         ##
@@ -379,36 +395,48 @@ module Google
         # @return [Google::Cloud::Logging::Entry::SourceLocation]
         attr_reader :source_location
 
+        ##
+        # The sampling decision of the trace associated with the log entry.
+        # Optional. A `true` value means that the trace resource name in the
+        # `trace` field was sampled for storage in a trace backend. A `false`
+        # means that the trace was not sampled for storage when this log entry
+        # was written, or the sampling decision was unknown at the time. A
+        # non-sampled `trace` value is still useful as a request correlation
+        # identifier. The default is `false`.
+        # @return [Boolean]
+        attr_accessor :trace_sampled
+
         ##
         # @private Determines if the Entry has any data.
         def empty?
           log_name.nil? &&
             timestamp.nil? &&
-            insert_id.nil? &&
             (labels.nil? || labels.empty?) &&
             payload.nil? &&
             resource.empty? &&
             http_request.empty? &&
             operation.empty? &&
             trace.nil? &&
-            source_location.empty?
+            source_location.empty? &&
+            trace_sampled.nil?
         end
 
         ##
         # @private Exports the Entry to a Google::Logging::V2::LogEntry object.
         def to_grpc
           grpc = Google::Logging::V2::LogEntry.new(
-            log_name: log_name.to_s,
-            timestamp: timestamp_grpc,
+            log_name:        log_name.to_s,
+            timestamp:       timestamp_grpc,
             # TODO: verify severity is the correct type?
-            severity: severity,
-            insert_id: insert_id.to_s,
-            labels: labels_grpc,
-            resource: resource.to_grpc,
-            http_request: http_request.to_grpc,
-            operation: operation.to_grpc,
-            trace: trace.to_s,
-            source_location: source_location.to_grpc
+            severity:        severity,
+            insert_id:       insert_id.to_s,
+            labels:          labels_grpc,
+            resource:        resource.to_grpc,
+            http_request:    http_request.to_grpc,
+            operation:       operation.to_grpc,
+            trace:           trace.to_s,
+            source_location: source_location.to_grpc,
+            trace_sampled:   !(!trace_sampled)
           )
           # Add payload
           append_payload grpc
@@ -437,6 +465,7 @@ module Google
                                     SourceLocation.from_grpc(
                                       grpc.source_location
                                     )
+            e.trace_sampled = grpc.trace_sampled
           end
         end
 
@@ -448,7 +477,7 @@ module Google
           # TODO: ArgumentError if timestamp is not a Time object?
           Google::Protobuf::Timestamp.new(
             seconds: timestamp.to_i,
-            nanos: timestamp.nsec
+            nanos:   timestamp.nsec
           )
         end
 
@@ -456,6 +485,7 @@ module Google
         # @private Formats the labels so they can be saved to a
         # Google::Logging::V2::LogEntry object.
         def labels_grpc
+          return {} if labels.nil?
           # Coerce symbols to strings
           Hash[labels.map do |k, v|
             v = String(v) if v.is_a? Symbol

data/lib/google/cloud/logging/entry/source_location.rb

@@ -61,9 +61,9 @@ module Google
           def to_grpc
             return nil if empty?
             Google::Logging::V2::LogEntrySourceLocation.new(
-              file:       file.to_s,
-              line:       line,
-              function:   function.to_s
+              file:     file.to_s,
+              line:     line,
+              function: function.to_s
             )
           end
 

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

@@ -0,0 +1,101 @@
+# Copyright 2018 Google LLC
+#
+# 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
+#
+#     https://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.
+
+
+require "google/cloud/errors"
+
+module Google
+  module Cloud
+    module Logging
+      ##
+      # # AsyncWriterError
+      #
+      # Used to indicate a problem preventing {AsyncWriter} from asynchronously
+      # calling the API. This can occur when the {AsyncWriter} has too few
+      # resources allocated for the amount of usage.
+      #
+      # @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, with entries
+      #     Google::Cloud::ErrorReporting.report error
+      #   end
+      #
+      #   logger = async.logger "my_app_log", resource, env: :production
+      #   logger.info "Job started."
+      #
+      class AsyncWriterError < Google::Cloud::Error
+        # @!attribute [r] count
+        #   @return [Array<Google::Cloud::Logging::Entry>] entries The entry
+        #   objects that were not written to the API due to the error.
+        attr_reader :entries
+
+        def initialize message, entries = nil
+          super(message)
+          @entries = entries if entries
+        end
+      end
+
+      ##
+      # # AsyncWriteEntriesError
+      #
+      # Used to indicate a problem when {AsyncWriter} writes log entries to the
+      # API. This can occur when the API returns an error.
+      #
+      # @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 AsyncWriteEntriesError, with entries
+      #     Google::Cloud::ErrorReporting.report error
+      #   end
+      #
+      #   logger = async.logger "my_app_log", resource, env: :production
+      #   logger.info "Job started."
+      #
+      class AsyncWriteEntriesError < Google::Cloud::Error
+        # @!attribute [r] count
+        #   @return [Array<Google::Cloud::Logging::Entry>] entries The entry
+        #   objects that were not written to the API due to the error.
+        attr_reader :entries
+
+        def initialize message, entries = nil
+          super(message)
+          @entries = entries if entries
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/logging/log/list.rb

@@ -73,7 +73,7 @@ module Google
             grpc = @service.list_logs token: token, resource: @resource,
                                       max: @max
             self.class.from_grpc grpc, @service, resource: @resource,
-                                                 max: @max
+                                                 max:      @max
           end
 
           ##

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

@@ -62,7 +62,7 @@ module Google
         # The log_name is a String that controls the name of the Stackdriver
         # log to write to. If it is nil, the default log_name for this Logger
         # is used.
-        RequestInfo = ::Struct.new :trace_id, :log_name, :env
+        RequestInfo = ::Struct.new :trace_id, :log_name, :env, :trace_sampled
 
         ##
         # The Google Cloud writer object that calls to `#write_entries` are made
@@ -456,8 +456,9 @@ module Google
         # @param [Hash, nil] env The request's Rack environment or `nil` if not
         #     available.
         #
-        def add_request_info info: nil, env: nil, trace_id: nil, log_name: nil
-          info ||= RequestInfo.new trace_id, log_name, env
+        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
 
@@ -549,11 +550,12 @@ module Google
             unless info.trace_id.nil? || @project.nil?
               entry.trace = "projects/#{@project}/traces/#{info.trace_id}"
             end
+            entry.trace_sampled = info.trace_sampled if entry.trace_sampled.nil?
           end
 
           writer.write_entries entry, log_name: actual_log_name,
                                       resource: resource,
-                                      labels: entry_labels(info)
+                                      labels:   entry_labels(info)
         end
 
         ##

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

@@ -28,7 +28,8 @@ module Google
         # A default value for the log_name_map argument. Directs health check
         # logs to a separate log name so they don't spam the main log.
         DEFAULT_LOG_NAME_MAP =
-          { "/_ah/health" => "ruby_health_check_log" }.freeze
+          { "/_ah/health" => "ruby_health_check_log",
+            "/healthz"    => "ruby_health_check_log" }.freeze
 
         ##
         # The Google::Cloud::Logging::Logger instance
@@ -43,6 +44,8 @@ module Google
         #   to track Stackdriver request trace ID. It also properly sets
         #   env["rack.logger"] to this assigned logger for accessing. If not
         #   specified, a default logger with be used.
+        # @param [Proc] on_init A callback to be invoked when the middleware is
+        #   initialized. The callback takes no arguments. Optional.
         # @param [Hash] kwargs Hash of configuration settings. Used for
         #   backward API compatibility. See the [Configuration
         #   Guide](https://googleapis.github.io/google-cloud-ruby/docs/stackdriver/latest/file.INSTRUMENTATION_CONFIGURATION)
@@ -51,23 +54,26 @@ module Google
         # @return [Google::Cloud::Logging::Middleware] A new
         #   Google::Cloud::Logging::Middleware instance
         #
-        def initialize app, logger: nil, **kwargs
+        def initialize app, logger: nil, on_init: nil, **kwargs
           @app = app
 
           load_config kwargs
 
-          if logger
-            @logger = logger
-          else
+          logger ||= Middleware.logger
+          logger ||= begin
             log_name = configuration.log_name
-            logging = Logging.new project_id: configuration.project_id,
+            logging = Logging.new project_id:  configuration.project_id,
                                   credentials: configuration.credentials
             resource = Middleware.build_monitored_resource(
               configuration.monitored_resource.type,
               configuration.monitored_resource.labels
             )
-            @logger = logging.logger log_name, resource
+            Middleware.logger = logging.logger log_name, resource
           end
+
+          on_init.call if on_init
+
+          @logger = logger
         end
 
         ##
@@ -185,6 +191,12 @@ module Google
           end
         end
 
+        class << self
+          ##
+          # @private Global logger object
+          attr_accessor :logger
+        end
+
         ##
         # @private Extract information from current environment and construct
         # the correct monitoring resource types and labels.
@@ -226,19 +238,20 @@ module Google
           type, labels =
             if Google::Cloud.env.app_engine?
               ["gae_app", {
-                module_id: Google::Cloud.env.app_engine_service_id,
+                module_id:  Google::Cloud.env.app_engine_service_id,
                 version_id: Google::Cloud.env.app_engine_service_version
               }]
             elsif Google::Cloud.env.container_engine?
+              namespace_id = Google::Cloud.env.container_engine_namespace_id
+              namespace_id ||= "default"
               ["container", {
                 cluster_name: Google::Cloud.env.container_engine_cluster_name,
-                namespace_id: \
-                  Google::Cloud.env.container_engine_namespace_id || "default"
+                namespace_id: namespace_id
               }]
             elsif Google::Cloud.env.compute_engine?
               ["gce_instance", {
                 instance_id: Google::Cloud.env.instance_name,
-                zone: Google::Cloud.env.instance_zone
+                zone:        Google::Cloud.env.instance_zone
               }]
             else
               ["global", {}]

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

@@ -206,8 +206,10 @@ module Google
         #
         def entry log_name: nil, resource: nil, timestamp: nil, severity: nil,
                   insert_id: nil, labels: nil, payload: nil
+          ensure_service!
+
           e = Entry.new
-          e.log_name = log_name if log_name
+          e.log_name = service.log_path(log_name) if log_name
           e.resource = resource if resource
           e.timestamp = timestamp if timestamp
           e.severity = severity if severity
@@ -240,8 +242,8 @@ module Google
         #   `entries`, except when a log entry specifies its own `key:value`
         #   item with the same key. See also {Entry#labels=}.
         # @param [Boolean] partial_success Whether valid entries should be
-        #   written even if some other entries fail due to INVALID_ARGUMENT or
-        #   PERMISSION_DENIED errors when communicating to the Stackdriver
+        #   written even if some other entries fail due to `INVALID_ARGUMENT` or
+        #   `PERMISSION_DENIED` errors when communicating to the Stackdriver
         #   Logging API.
         #
         # @return [Boolean] Returns `true` if the entries were written.
@@ -304,22 +306,36 @@ module Google
         end
 
         ##
-        # Creates an object that batches and transmits log entries
-        # asynchronously.
+        # Creates an object that buffers, batches, and transmits log entries
+        # efficiently. Writing log entries to this object is asynchronous and
+        # will not block.
         #
-        # 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.
+        # 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 {AsyncWriter#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.
         #
-        # @param [Integer] max_queue_size The maximum number of log entries
-        #   that may be queued before write requests will begin to block.
-        #   This provides back pressure in case the transmitting thread cannot
-        #   keep up with requests.
+        # @param [Integer] max_batch_count The maximum number of log entries
+        #   that may be buffered and sent in a batch.
+        # @param [Integer] max_batch_bytes The maximum byte size of log entries
+        #   that may be buffered and sent in a batch.
+        # @param [Integer] max_queue_size The maximum number of pending
+        #   write_entries requests that may be queued.
+        # @param [Numeric] interval The number of seconds to buffer log entries
+        #   before a batch is written. Default is 5.
+        # @param [Integer] threads The number of threads used to make
+        #   batched write_entries requests. Default is 10.
+        # @param [Boolean] partial_success Whether valid entries should be
+        #   written even if some other entries fail due to `INVALID_ARGUMENT` or
+        #   `PERMISSION_DENIED` errors when communicating to the Stackdriver
+        #   Logging API.
+        #
+        # @return [Google::Cloud::Logging::AsyncWriter] an AsyncWriter object
+        #   that buffers, batches, and transmits log entries efficiently.
         #
         # @example
         #   require "google/cloud/logging"
@@ -341,8 +357,15 @@ module Google
         #                       resource: resource,
         #                       labels: labels
         #
-        def async_writer max_queue_size: AsyncWriter::DEFAULT_MAX_QUEUE_SIZE
-          AsyncWriter.new self, max_queue_size
+        def async_writer max_batch_count: 10000, max_batch_bytes: 10000000,
+                         max_queue_size: 100, interval: 5, threads: 10,
+                         partial_success: false
+
+          AsyncWriter.new self, max_count: max_batch_count,
+                                max_bytes: max_batch_bytes,
+                                max_queue: max_queue_size,
+                                interval: interval, threads: threads,
+                                partial_success: partial_success
         end
 
         ##