gcloud 0.11.0 → 0.12.0

data/lib/gcloud/logging.rb

@@ -18,14 +18,14 @@ require "gcloud/logging/project"
 
 module Gcloud
   ##
-  # Creates a new object for connecting to the Logging service.
+  # 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/gcloud-ruby/#/docs/guides/authentication).
   #
-  # @param [String] project Project identifier for the Logging service you are
-  #   connecting to.
+  # @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
@@ -36,6 +36,9 @@ module Gcloud
   #   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.
   #
   # @return [Gcloud::Logging::Project]
   #
@@ -46,23 +49,30 @@ module Gcloud
   #   logging = gcloud.logging
   #   # ...
   #
-  def self.logging project = nil, keyfile = nil, scope: nil
+  def self.logging project = nil, keyfile = nil, scope: nil, retries: nil,
+                   timeout: nil
     project ||= Gcloud::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 = Gcloud::Logging::Credentials.default scope: scope
     else
       credentials = Gcloud::Logging::Credentials.new keyfile, scope: scope
     end
-    Gcloud::Logging::Project.new project, credentials
+
+    Gcloud::Logging::Project.new(
+      Gcloud::Logging::Service.new(
+        project, credentials, retries: retries, timeout: timeout))
   end
 
   ##
-  # # Google Cloud Logging
+  # # Stackdriver Logging
   #
-  # The Google Cloud Logging service collects and stores logs from applications
+  # The Stackdriver Logging service collects and stores logs from applications
   # and services on the Google Cloud Platform, giving you fine-grained,
-  # programmatic control over your projects' logs. You can use the Cloud Logging
-  # API to:
+  # programmatic control over your projects' logs. You can use the Stackdriver
+  # Logging API to:
   #
   # * [Read and filter log entries](#listing-log-entries)
   # * [Export your log entries](#exporting-log-entries) to Cloud Storage,
@@ -71,21 +81,21 @@ module Gcloud
   #   Monitoring
   # * [Write log entries](#writing-log-entries)
   #
-  # For general information about Cloud Logging, read [What is Google Cloud
-  # Logging?](https://cloud.google.com/logging/docs/).
+  # For general information about Stackdriver Logging, read [Stackdriver Logging
+  # Documentation](https://cloud.google.com/logging/docs/).
   #
-  # Gcloud's goal is to provide an API that is familiar and comfortable to
+  # The goal of gcloud-ruby is to provide an API that is comfortable to
   # Rubyists. Authentication is handled by {Gcloud#logging}. You can provide the
-  # project and credential information to connect to the Cloud Logging service,
-  # or if you are running on Google Compute Engine this configuration is taken
-  # care of for you. You can read more about the options for connecting in the
-  # [Authentication
+  # project and credential information to connect to the Stackdriver Logging
+  # service, or if you are running on Google Compute Engine this configuration
+  # is taken care of for you. You can read more about the options for connecting
+  # in the [Authentication
   # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
   # ## Listing log entries
   #
-  # Cloud Logging gathers log entries from many services, including Google App
-  # Engine and Google Compute Engine. (See the [List of Log
+  # Stackdriver Logging gathers log entries from many services, including Google
+  # App Engine and Google Compute Engine. (See the [List of Log
   # Types](https://cloud.google.com/logging/docs/view/logs_index).) In addition,
   # you can write your own log entries to the service.
   #
@@ -108,8 +118,9 @@ module Gcloud
   # log is a named collection of entries. Logs can be produced by Google Cloud
   # Platform services, by third-party services, or by your applications. For
   # example, the log `compute.googleapis.com/activity_log` is produced by Google
-  # Compute Engine. Logs are simply referenced by name in Gcloud. There is no
-  # `Log` type in Gcloud or `Log` resource in the Cloud Logging API.
+  # Compute Engine. Logs are simply referenced by name in gcloud-ruby. There is
+  # no `Log` type in gcloud-ruby or `Log` resource in the Stackdriver Logging
+  # API.
   #
   # ```ruby
   # require "gcloud"
@@ -137,9 +148,9 @@ module Gcloud
   #
   # ## Exporting log entries
   #
-  # Cloud Logging lets you export log entries to destinations including Google
-  # Cloud Storage buckets (for long term log storage), Google BigQuery datasets
-  # (for log analysis), and Google Pub/Sub (for streaming to other
+  # Stackdriver Logging lets you export log entries to destinations including
+  # Google Cloud Storage buckets (for long term log storage), Google BigQuery
+  # datasets (for log analysis), and Google Pub/Sub (for streaming to other
   # applications).
   #
   # ### Creating sinks
@@ -166,15 +177,16 @@ module Gcloud
   #
   # bucket = storage.create_bucket "my-logs-bucket"
   #
-  # # Grant owner permission to Cloud Logging service
+  # # Grant owner permission to Stackdriver Logging service
   # email = "cloud-logs@google.com"
   # bucket.acl.add_owner "group-#{email}"
   #
   # sink = logging.create_sink "my-sink", "storage.googleapis.com/#{bucket.id}"
   # ```
   #
-  # When you create a sink, only new log entries are exported. Cloud Logging
-  # does not send previously-ingested log entries to the sink's destination.
+  # When you create a sink, only new log entries are exported. Stackdriver
+  # Logging does not send previously-ingested log entries to the sink's
+  # destination.
   #
   # ### Listing sinks
   #
@@ -233,7 +245,7 @@ module Gcloud
   # ## Writing log entries
   #
   # An {Gcloud::Logging::Entry} is composed of metadata and a payload. The
-  # payload is traditionally a message string, but in Cloud Logging it can
+  # payload is traditionally a message string, but in Stackdriver Logging it can
   # also be a JSON or protocol buffer object. A single log can have entries with
   # different payload types. In addition to the payload, your argument(s) to
   # {Gcloud::Logging::Project#write_entries} must also contain a log name and a
@@ -302,24 +314,23 @@ module Gcloud
   # logger.info "Job started."
   # ```
   #
-  # ## Configuring Backoff
+  # ## Configuring retries and timeout
   #
-  # The {Gcloud::Backoff} class allows users to globally configure how Cloud API
-  # requests are automatically retried in the case of some errors, such as a
-  # `500` or `503` status code, or a specific internal error code such as
-  # `rateLimitExceeded`.
+  # 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.
   #
-  # If an API call fails, the response will be inspected to see if the call
-  # should be retried. If the response matches the criteria, then the request
-  # will be retried after a delay. If another error occurs, the delay will be
-  # increased incrementally before a subsequent attempt. The first retry will be
-  # delayed one second, the second retry two seconds, and so on.
+  # You can also set the request `timeout` value in seconds.
   #
   # ```ruby
   # require "gcloud"
-  # require "gcloud/backoff"
   #
-  # Gcloud::Backoff.retries = 5 # Raise the maximum number of retries from 3
+  # gcloud = Gcloud.new
+  # logging = gcloud.logging retries: 10, timeout: 120
   # ```
   #
   module Logging

data/lib/gcloud/logging/entry.rb

@@ -27,17 +27,18 @@ module Gcloud
     # An individual entry in a log.
     #
     # Each log entry is composed of metadata and a payload. The metadata
-    # includes standard information used by Cloud Logging, such as when the
-    # entry was created and where it came from. The payload is the event record.
-    # Traditionally this is a message string, but in Cloud Logging it can also
-    # be a JSON or protocol buffer object. A single log can have entries with
-    # different payload types.
+    # includes standard information used by Stackdriver Logging, such as when
+    # the entry was created and where it came from. The payload is the event
+    # record. Traditionally this is a message string, but in Stackdriver Logging
+    # it can also be a JSON or protocol buffer object. A single log can have
+    # entries with different payload types.
     #
     # A log is a named collection of entries. Logs can be produced by Google
     # Cloud Platform services, by third-party services, or by your applications.
     # For example, the log `compute.googleapis.com/activity_log` is produced by
-    # Google Compute Engine. Logs are simply referenced by name in Gcloud. There
-    # is no `Log` type in Gcloud or `Log` resource in the Cloud Logging API.
+    # Google Compute Engine. Logs are simply referenced by name in gcloud-ruby.
+    # There is no `Log` type in gcloud-ruby or `Log` resource in the Cloud
+    # Logging API.
     #
     # @see https://cloud.google.com/logging/docs/view/logs_index List of Log
     #   Types
@@ -48,9 +49,7 @@ module Gcloud
     #   gcloud = Gcloud.new
     #   logging = gcloud.logging
     #
-    #   entry = logging.entry
-    #   entry.payload = "Job started."
-    #   entry.log_name = "my_app_log"
+    #   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"
@@ -89,76 +88,250 @@ module Gcloud
       # monitored resource designating the particular database that reported the
       # error.
       # @return [Gcloud::Logging::Resource]
-      attr_reader :resource
+      attr_accessor :resource
 
       ##
       # The time the event described by the log entry occurred. If omitted,
-      # Cloud Logging will use the time the log entry is written.
+      # Stackdriver Logging will use the time the log entry is written.
+      # @return [Time]
       attr_accessor :timestamp
 
       ##
-      # The severity level of the log entry. The default value is `DEFAULT`.
+      # The severity level of the log entry. The default value is `:DEFAULT`.
+      # @return [Symbol]
       attr_accessor :severity
 
       ##
-      # Returns `true` if the severity level is `DEFAULT`.
+      # Returns `true` if the severity level is `:DEFAULT`.
       def default?
         severity == :DEFAULT
       end
 
       ##
-      # Returns `true` if the severity level is `DEBUG`.
+      # Sets the severity level to `:DEFAULT`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity = :DEBUG
+      #   entry.default!
+      #   entry.default? #=> true
+      #   entry.severity #=> :DEFAULT
+      #
+      def default!
+        self.severity = :DEFAULT
+      end
+
+      ##
+      # Returns `true` if the severity level is `:DEBUG`.
       def debug?
         severity == :DEBUG
       end
 
       ##
-      # Returns `true` if the severity level is `INFO`.
+      # Sets the severity level to `:DEBUG`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.debug!
+      #   entry.debug? #=> true
+      #   entry.severity #=> :DEBUG
+      #
+      def debug!
+        self.severity = :DEBUG
+      end
+
+      ##
+      # Returns `true` if the severity level is `:INFO`.
       def info?
         severity == :INFO
       end
 
       ##
-      # Returns `true` if the severity level is `NOTICE`.
+      # Sets the severity level to `:INFO`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.info!
+      #   entry.info? #=> true
+      #   entry.severity #=> :INFO
+      #
+      def info!
+        self.severity = :INFO
+      end
+
+      ##
+      # Returns `true` if the severity level is `:NOTICE`.
       def notice?
         severity == :NOTICE
       end
 
       ##
-      # Returns `true` if the severity level is `WARNING`.
+      # Sets the severity level to `:NOTICE`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.notice!
+      #   entry.notice? #=> true
+      #   entry.severity #=> :NOTICE
+      #
+      def notice!
+        self.severity = :NOTICE
+      end
+
+      ##
+      # Returns `true` if the severity level is `:WARNING`.
       def warning?
         severity == :WARNING
       end
 
       ##
-      # Returns `true` if the severity level is `ERROR`.
+      # Sets the severity level to `:WARNING`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.warning!
+      #   entry.warning? #=> true
+      #   entry.severity #=> :WARNING
+      #
+      def warning!
+        self.severity = :WARNING
+      end
+
+      ##
+      # Returns `true` if the severity level is `:ERROR`.
       def error?
         severity == :ERROR
       end
 
       ##
-      # Returns `true` if the severity level is `CRITICAL`.
+      # Sets the severity level to `:ERROR`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.error!
+      #   entry.error? #=> true
+      #   entry.severity #=> :ERROR
+      #
+      def error!
+        self.severity = :ERROR
+      end
+
+      ##
+      # Returns `true` if the severity level is `:CRITICAL`.
       def critical?
         severity == :CRITICAL
       end
 
       ##
-      # Returns `true` if the severity level is `ALERT`.
+      # Sets the severity level to `:CRITICAL`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.critical!
+      #   entry.critical? #=> true
+      #   entry.severity #=> :CRITICAL
+      #
+      def critical!
+        self.severity = :CRITICAL
+      end
+
+      ##
+      # Returns `true` if the severity level is `:ALERT`.
       def alert?
         severity == :ALERT
       end
 
       ##
-      # Returns `true` if the severity level is `EMERGENCY`.
+      # Sets the severity level to `:ALERT`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.alert!
+      #   entry.alert? #=> true
+      #   entry.severity #=> :ALERT
+      #
+      def alert!
+        self.severity = :ALERT
+      end
+
+      ##
+      # Returns `true` if the severity level is `:EMERGENCY`.
       def emergency?
         severity == :EMERGENCY
       end
 
+      ##
+      # Sets the severity level to `:EMERGENCY`.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #
+      #   entry = logging.entry
+      #   entry.severity #=> :DEFAULT
+      #   entry.emergency!
+      #   entry.emergency? #=> true
+      #   entry.severity #=> :EMERGENCY
+      #
+      def emergency!
+        self.severity = :EMERGENCY
+      end
+
       ##
       # A unique ID for the log entry. If you provide this field, the logging
       # service considers other log entries in the same log with the same ID as
-      # duplicates which can be removed. If omitted, Cloud Logging will generate
-      # a unique ID for this log entry.
+      # duplicates which can be removed. If omitted, Stackdriver Logging will
+      # generate a unique ID for this log entry.
+      # @return [String]
       attr_accessor :insert_id
 
       ##