google-cloud-logging 0.20.0

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

@@ -0,0 +1,145 @@
+# 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
+      class Entry
+        ##
+        # # Http Request
+        #
+        # HTTP request data associated with a log entry.
+        #
+        # See also {Google::Cloud::Logging::Entry#http_request}.
+        #
+        class HttpRequest
+          ##
+          # @private Create an empty HttpRequest object.
+          def initialize
+          end
+
+          ##
+          # The request method. Examples: `"GET"`, `"HEAD"`, `"PUT"`, `"POST"`.
+          # (String)
+          attr_accessor :method
+
+          ##
+          # The URL. The scheme (http, https), the host name, the path and the
+          # query portion of the URL that was requested. Example:
+          # `"http://example.com/some/info?color=red"`. (String)
+          attr_accessor :url
+
+          ##
+          # The size of the HTTP request message in bytes, including the request
+          # headers and the request body. (Integer)
+          attr_accessor :size
+
+          ##
+          # The response code indicating the status of response. Examples:
+          # `200`, `404`. (Integer)
+          attr_accessor :status
+
+          ##
+          # The size of the HTTP response message sent back to the client, in
+          # bytes, including the response headers and the response body.
+          # (Integer)
+          attr_accessor :response_size
+
+          ##
+          # The user agent sent by the client. Example: `"Mozilla/4.0
+          # (compatible; MSIE 6.0; Windows 98; Q312461; .NET CLR 1.0.3705)"`.
+          # (String)
+          attr_accessor :user_agent
+
+          ##
+          # The IP address (IPv4 or IPv6) of the client that issued the HTTP
+          # request. Examples: `"192.168.1.1"`, `"FE80::0202:B3FF:FE1E:8329"`.
+          # (String)
+          attr_accessor :remote_ip
+
+          ##
+          # The referer URL of the request, as defined in [HTTP/1.1 Header Field
+          # Definitions](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).
+          # (String)
+          attr_accessor :referer
+
+          ##
+          # Whether an entity was served from cache (with or without
+          # validation). (Boolean)
+          attr_accessor :cache_hit
+
+          ##
+          # Whether the response was validated with the origin server before
+          # being served from cache. This field is only meaningful if
+          # `cache_hit` is `true`. (Boolean)
+          attr_accessor :validated
+
+          ##
+          # @private Determines if the HttpRequest has any data.
+          def empty?
+            method.nil? &&
+              url.nil? &&
+              size.nil? &&
+              status.nil? &&
+              response_size.nil? &&
+              user_agent.nil? &&
+              remote_ip.nil? &&
+              referer.nil? &&
+              cache_hit.nil? &&
+              validated.nil?
+          end
+
+          ##
+          # @private Exports the HttpRequest to a
+          # Google::Logging::Type::HttpRequest object.
+          def to_grpc
+            return nil if empty?
+            Google::Logging::Type::HttpRequest.new(
+              request_method:                     method.to_s,
+              request_url:                        url.to_s,
+              request_size:                       size.to_i,
+              status:                             status.to_i,
+              response_size:                      response_size.to_i,
+              user_agent:                         user_agent.to_s,
+              remote_ip:                          remote_ip.to_s,
+              referer:                            referer.to_s,
+              cache_hit:                          !(!cache_hit),
+              cache_validated_with_origin_server: !(!validated)
+            )
+          end
+
+          ##
+          # @private New HttpRequest from a Google::Logging::Type::HttpRequest
+          # object.
+          def self.from_grpc grpc
+            return new if grpc.nil?
+            new.tap do |h|
+              h.method        = grpc.request_method
+              h.url           = grpc.request_url
+              h.size          = grpc.request_size
+              h.status        = grpc.status
+              h.response_size = grpc.response_size
+              h.user_agent    = grpc.user_agent
+              h.remote_ip     = grpc.remote_ip
+              h.referer       = grpc.referer
+              h.cache_hit     = grpc.cache_hit
+              h.validated     = grpc.cache_validated_with_origin_server
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,180 @@
+# 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.
+
+
+require "delegate"
+
+module Google
+  module Cloud
+    module Logging
+      class Entry
+        ##
+        # Entry::List is a special case Array with additional values.
+        class List < DelegateClass(::Array)
+          ##
+          # If not empty, indicates that there are more records that match
+          # the request and this value should be passed to continue.
+          attr_accessor :token
+
+          ##
+          # @private Create a new Entry::List with an array of Entry instances.
+          def initialize arr = []
+            super arr
+          end
+
+          ##
+          # Whether there is a next page of entries.
+          #
+          # @return [Boolean]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #
+          #   entries = logging.entries
+          #   if entries.next?
+          #     next_entries = entries.next
+          #   end
+          #
+          def next?
+            !token.nil?
+          end
+
+          ##
+          # Retrieve the next page of entries.
+          #
+          # @return [Sink::List]
+          #
+          # @example
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #
+          #   entries = dataset.entries
+          #   if entries.next?
+          #     next_entries = entries.next
+          #   end
+          #
+          def next
+            return nil unless next?
+            ensure_service!
+            grpc = @service.list_entries token: token, projects: @projects,
+                                         filter: @filter, order: @order,
+                                         max: @max
+            self.class.from_grpc grpc, @service
+          end
+
+          ##
+          # Retrieves all log entries by repeatedly loading {#next} until
+          # {#next?} returns `false`. Calls the given block once for each log
+          # entry, which is passed as the parameter.
+          #
+          # An Enumerator is returned if no block is given.
+          #
+          # This method may make several API calls until all log entries are
+          # retrieved. Be sure to use as narrow a search criteria as possible.
+          # Please use with caution.
+          #
+          # @param [Integer] request_limit The upper limit of API requests to
+          #   make to load all log entries. Default is no limit.
+          # @yield [entry] The block for accessing each log entry.
+          # @yieldparam [Entry] entry The log entry object.
+          #
+          # @return [Enumerator]
+          #
+          # @example Iterating each log entry by passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #   entries = logging.entries order: "timestamp desc"
+          #
+          #   entries.all do |entry|
+          #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+          #   end
+          #
+          # @example Using the enumerator by not passing a block:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #   entries = logging.entries order: "timestamp desc"
+          #
+          #   all_payloads = entries.all.map do |entry|
+          #     entry.payload
+          #   end
+          #
+          # @example Limit the number of API calls made:
+          #   require "google/cloud"
+          #
+          #   gcloud = Google::Cloud.new
+          #   logging = gcloud.logging
+          #   entries = logging.entries order: "timestamp desc"
+          #
+          #   entries.all(request_limit: 10) do |entry|
+          #     puts "[#{e.timestamp}] #{e.log_name} #{e.payload.inspect}"
+          #   end
+          #
+          def all request_limit: nil
+            request_limit = request_limit.to_i if request_limit
+            unless block_given?
+              return enum_for(:all, request_limit: request_limit)
+            end
+            results = self
+            loop do
+              results.each { |r| yield r }
+              if request_limit
+                request_limit -= 1
+                break if request_limit < 0
+              end
+              break unless results.next?
+              results = results.next
+            end
+          end
+
+          ##
+          # @private New Entry::List from a
+          # Google::Logging::V2::ListLogEntryResponse object.
+          def self.from_grpc grpc_list, service, projects: nil, filter: nil,
+                             order: nil, max: nil
+            entries = new(Array(grpc_list.entries).map do |grpc_entry|
+              Entry.from_grpc grpc_entry
+            end)
+            token = grpc_list.next_page_token
+            token = nil if token == ""
+            entries.instance_variable_set "@token", token
+            entries.instance_variable_set "@service", service
+            entries.instance_variable_set "@projects", projects
+            entries.instance_variable_set "@filter", filter
+            entries.instance_variable_set "@order", order
+            entries.instance_variable_set "@max", max
+            entries
+          end
+
+          protected
+
+          ##
+          # @private Raise an error unless an active connection to the service
+          # is available.
+          def ensure_service!
+            fail "Must have active connection to service" unless @service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# 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
+      class Entry
+        ##
+        # # Operation
+        #
+        # Additional information about a potentially long-running operation with
+        # which a log entry is associated.
+        #
+        # See also {Google::Cloud::Logging::Entry#operation}.
+        #
+        class Operation
+          ##
+          # @private Create an empty Operation object.
+          def initialize
+          end
+
+          ##
+          # An arbitrary operation identifier. Log entries with the same
+          # identifier are assumed to be part of the same operation.
+          attr_accessor :id
+
+          ##
+          # An arbitrary producer identifier. The combination of `id` and
+          # `producer` must be globally unique. Examples for `producer`:
+          # `"MyDivision.MyBigCompany.com"`,
+          # `"github.com/MyProject/MyApplication"`.
+          attr_accessor :producer
+
+          ##
+          # Set this to `true` if this is the first log entry in the operation.
+          attr_accessor :first
+
+          ##
+          # Set this to `true` if this is the last log entry in the operation.
+          attr_accessor :last
+
+          ##
+          # @private Determines if the Operation has any data.
+          def empty?
+            id.nil? &&
+              producer.nil? &&
+              first.nil? &&
+              last.nil?
+          end
+
+          ##
+          # @private Exports the Operation to a
+          # Google::Logging::V2::LogEntryOperation object.
+          def to_grpc
+            return nil if empty?
+            Google::Logging::V2::LogEntryOperation.new(
+              id:       id.to_s,
+              producer: producer.to_s,
+              first:    !(!first),
+              last:     !(!last)
+            )
+          end
+
+          ##
+          # @private New HttpRequest from a
+          # Google::Logging::V2::LogEntryOperation object.
+          def self.from_grpc grpc
+            return new if grpc.nil?
+            new.tap do |o|
+              o.id       = grpc.id
+              o.producer = grpc.producer
+              o.first    = grpc.first
+              o.last     = grpc.last
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,309 @@
+# 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
+      ##
+      # # Logger
+      #
+      # A (mostly) API-compatible logger for ruby's Logger.
+      #
+      # @example
+      #   require "google/cloud"
+      #
+      #   gcloud = Google::Cloud.new
+      #   logging = gcloud.logging
+      #
+      #   resource = logging.resource "gae_app",
+      #                               module_id: "1",
+      #                               version_id: "20150925t173233"
+      #
+      #   logger = logging.logger "my_app_log", resource, env: :production
+      #   logger.info "Job started."
+      #
+      class Logger
+        ##
+        # @private The logging object.
+        attr_accessor :logging
+
+        ##
+        # @private The Google Cloud log_name to write the log entry with.
+        attr_reader :log_name
+
+        ##
+        # @private The Google Cloud resource to write the log entry with.
+        attr_reader :resource
+
+        ##
+        # @private The Google Cloud labels to write the log entry with.
+        attr_reader :labels
+
+        ##
+        # @private Creates a new Logger instance.
+        def initialize logging, log_name, resource, labels = nil
+          @logging = logging
+          @log_name = log_name
+          @resource = resource
+          @labels = labels
+          @level = 0 # DEBUG is the default behavior
+        end
+
+        ##
+        # Log a `DEBUG` entry.
+        #
+        # @param [String, Hash] message The log entry payload, represented as
+        #   either a string, a hash (JSON), or a hash (protocol buffer).
+        # @yield 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.
+        #
+        def debug message = nil, &block
+          if block_given?
+            add 0, nil, message, &block
+          else
+            add 0, message, nil, &block
+          end
+        end
+
+        ##
+        # Log an `INFO` entry.
+        #
+        # @param [String, Hash] message The log entry payload, represented as
+        #   either a string, a hash (JSON), or a hash (protocol buffer).
+        # @yield 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.
+        #
+        def info message = nil, &block
+          if block_given?
+            add 1, nil, message, &block
+          else
+            add 1, message, nil, &block
+          end
+        end
+
+        ##
+        # Log a `WARN` entry.
+        #
+        # @param [String, Hash] message The log entry payload, represented as
+        #   either a string, a hash (JSON), or a hash (protocol buffer).
+        # @yield 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.
+        #
+        def warn message = nil, &block
+          if block_given?
+            add 2, nil, message, &block
+          else
+            add 2, message, nil, &block
+          end
+        end
+
+        ##
+        # Log an `ERROR` entry.
+        #
+        # @param [String, Hash] message The log entry payload, represented as
+        #   either a string, a hash (JSON), or a hash (protocol buffer).
+        # @yield 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.
+        #
+        def error message = nil, &block
+          if block_given?
+            add 3, nil, message, &block
+          else
+            add 3, message, nil, &block
+          end
+        end
+
+        ##
+        # Log a `FATAL` entry.
+        #
+        # @param [String, Hash] message The log entry payload, represented as
+        #   either a string, a hash (JSON), or a hash (protocol buffer).
+        # @yield 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.
+        #
+        def fatal message = nil, &block
+          if block_given?
+            add 4, nil, message, &block
+          else
+            add 4, message, nil, &block
+          end
+        end
+
+        ##
+        # Log an `UNKNOWN` entry. This will be printed no matter what the
+        # logger's current severity level is.
+        #
+        # @param [String, Hash] message The log entry payload, represented as
+        #   either a string, a hash (JSON), or a hash (protocol buffer).
+        # @yield 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.
+        #
+        def unknown message = nil, &block
+          if block_given?
+            add 5, nil, message, &block
+          else
+            add 5, message, nil, &block
+          end
+        end
+
+        ##
+        # 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}.
+        #
+        # @param [Integer, String, Symbol] severity the integer code for or the
+        #   name of the severity level
+        # @param [String, Hash] message The log entry payload, represented as
+        #   either a string, a hash (JSON), or a hash (protocol buffer).
+        # @yield 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.
+        #
+        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
+        alias_method :log, :add
+
+        ##
+        # Returns `true` if the current severity level allows for sending
+        # `DEBUG` messages.
+        def debug?
+          @level <= 0
+        end
+
+        ##
+        # Returns `true` if the current severity level allows for sending `INFO`
+        # messages.
+        def info?
+          @level <= 1
+        end
+
+        ##
+        # Returns `true` if the current severity level allows for sending `WARN`
+        # messages.
+        def warn?
+          @level <= 2
+        end
+
+        ##
+        # Returns `true` if the current severity level allows for sending
+        # `ERROR` messages.
+        def error?
+          @level <= 3
+        end
+
+        ##
+        # Returns `true` if the current severity level allows for sending
+        # `FATAL` messages.
+        def fatal?
+          @level <= 4
+        end
+
+        ##
+        # Sets the logging severity level.
+        #
+        # @param [Integer, String, Symbol] severity the integer code for or the
+        #   name of the severity level
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   gcloud = Google::Cloud.new
+        #   logging = gcloud.logging
+        #
+        #   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
+        #
+        def level= severity
+          new_level = derive_severity severity
+          fail ArgumentError, "invalid log level: #{severity}" if new_level.nil?
+          @level = new_level
+        end
+        alias_method :sev_threshold=, :level=
+
+        protected
+
+        ##
+        # @private Write a log entry to the Stackdriver Logging service.
+        def write_entry severity, message
+          entry = logging.entry.tap do |e|
+            e.severity = gcloud_severity(severity)
+            e.payload = message
+          end
+
+          logging.write_entries entry, log_name: log_name,
+                                       resource: resource,
+                                       labels: labels
+        end
+
+        ##
+        # @private Get the logger level number from severity value object.
+        def derive_severity severity
+          return severity if severity.is_a? Integer
+
+          downcase_severity = severity.to_s.downcase
+          case downcase_severity
+          when "debug".freeze then 0
+          when "info".freeze then 1
+          when "warn".freeze then 2
+          when "error".freeze then 3
+          when "fatal".freeze then 4
+          when "unknown".freeze then 5
+          else nil
+          end
+        end
+
+        ##
+        # @private Get Google Cloud deverity from logger level number.
+        def gcloud_severity severity_int
+          %i(DEBUG INFO WARNING ERROR CRITICAL DEFAULT)[severity_int]
+        rescue
+          :DEFAULT
+        end
+      end
+    end
+  end
+end