gcloud 0.6.3 → 0.7.0

data/lib/gcloud/logging/entry/http_request.rb

@@ -0,0 +1,141 @@
+# 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 Gcloud
+  module Logging
+    class Entry
+      ##
+      # # Http Request
+      #
+      # HTTP request data associated with a log entry.
+      #
+      # See also {Gcloud::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),
+            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.validated_with_origin_server
+          end
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/logging/entry/list.rb

@@ -0,0 +1,111 @@
+# 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 Gcloud
+  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.
+        def next?
+          !token.nil?
+        end
+
+        ##
+        # Retrieve the next page of entries.
+        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
+        rescue GRPC::BadStatus => e
+          raise Gcloud::Error.from_error(e)
+        end
+
+        ##
+        # Retrieves all log entries by repeatedly loading {#next} until
+        # {#next?} returns `false`. Returns the list instance for method
+        # chaining.
+        #
+        # 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.
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   hour_ago = (Time.now - 60*60).utc.strftime('%FT%TZ')
+        #   recent_errors = "timestamp >= \"#{hour_ago}\" severity >= ERROR"
+        #   entries = logging.entries(filter: recent_errors).all
+        #
+        def all
+          while next?
+            next_records = self.next
+            push(*next_records)
+            self.token = next_records.token
+          end
+          self
+        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)
+          entries.instance_eval do
+            @token = grpc_list.next_page_token
+            @token = nil if @token == ""
+            @service = service
+            @projects = projects
+            @filter = filter
+            @order = order
+            @max = max
+          end
+          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

data/lib/gcloud/logging/entry/operation.rb

@@ -0,0 +1,90 @@
+# 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 Gcloud
+  module Logging
+    class Entry
+      ##
+      # # Operation
+      #
+      # Additional information about a potentially long-running operation with
+      # which a log entry is associated.
+      #
+      # See also {Gcloud::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

data/lib/gcloud/logging/logger.rb

@@ -0,0 +1,307 @@
+# 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 Gcloud
+  module Logging
+    ##
+    # # Logger
+    #
+    # A (mostly) API-compatible logger for ruby's Logger.
+    #
+    # @example
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.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 "gcloud"
+      #
+      #   gcloud = Gcloud.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 Google Cloud 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