google-cloud-error_reporting 0.27.0 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 3b8ac0c9f4b208544f69fc27cab36f0746148b8a
-  data.tar.gz: 8445acf96064da8d26b0d37d6140d7a687cdcaa7
+SHA256:
+  metadata.gz: 5ce7d566383abf96959435e8f9a50a02a5572c57a40b5a12b6dafe2374b0df0b
+  data.tar.gz: 32bc529ffd05720f2a560536d44ef1dc98295f7aa0b82e155071de9b9f62fd96
 SHA512:
-  metadata.gz: 4d150f67b1a2255a1c2c7f6df9437b37c9ccb2d9447b43e6d020ab60440a5d69cff47174ecd5eb5b6538638c63e10ba0fae4e4925b34f46ab7568ed32abd0575
-  data.tar.gz: 6c3ca9dc7421944c1d2ccee71d2bfaae86c20f26b50452b8ade4886b0bb05fb5ff27f9690bb93676e9a56325e8d005bd021ca725b59c74d1e4749d27d06645ac
+  metadata.gz: aecb1e6162d607ae4406bbfe832b82e83ec3ecf11a470f73fbe05babc38b75307aecae6a677ebc864328854c343196231c216180d2efde256d9343d9f2cf4a74
+  data.tar.gz: bedc1b1736c010cacd97782bc2b2dc47134087735367ae8f28eb62c460dc7f611425e4f9b6d364a49069ca2525b919b9b317ece027885d7ccca30e8730dc78cf

data/README.md

@@ -13,63 +13,170 @@ new errors.
 - [google-cloud-error_reporting on RubyGems](https://rubygems.org/gems/google-cloud-error_reporting)
 - [Stackdriver ErrorReporting documentation](https://cloud.google.com/error-reporting/docs/)
 
-google-cloud-error_reporting provides an instrumentation API that makes it easy 
-to report exceptions to the Stackdriver Error Reporting service. It also 
-contains a full API client library for the 
-[Stackdriver Error Reporting API](https://developers.google.com/apis-explorer/#p/clouderrorreporting/v1beta1/) 
-(v1beta1).
-
 ## Quick Start
+
+Install the gem directly:
+
 ```sh
 $ gem install google-cloud-error_reporting
 ```
 
-## Authentication
+Or install through Bundler:
 
-The Instrumentation client and API use Service Account credentials to connect 
-to Google Cloud services. When running on Google Cloud Platform environments, 
-the credentials will be discovered automatically. When running on other 
-environments the Service Account credentials can be specified by providing the 
-path to the JSON file, or the JSON itself, in environment variables or 
-configuration code.
+1. Add the `google-cloud-error_reporting` gem to your Gemfile:
+
+```ruby
+gem "google-cloud-error_reporting"
+```
+
+2. Use Bundler to install the gem:
+
+```sh
+$ bundle install
+```
+
+Alternatively, check out the [`stackdriver`](../stackdriver) gem that includes 
+the `google-cloud-error_reporting` gem.
+
+## Enable Stackdriver Error Reporting API
+
+The Stackdriver Error Reporting library needs the [Stackdriver Error
+Reporting API](https://console.cloud.google.com/apis/library/clouderrorreporting.googleapis.com) 
+to be enabled on your Google Cloud project. Make sure it's enabled if not 
+already.
 
-Instructions and configuration options are covered in the 
-[Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/authentication).
+## Reporting errors in Rack-based frameworks
+
+The Stackdriver Error Reporting library for Ruby makes it easy to integrate 
+Stackdriver Error Reporting into popular Rack-based Ruby web frameworks such as 
+Ruby on Rails and Sinatra. When the library integration is enabled, it 
+automatically reports exceptions captured from the application's Rack stack.
+
+### With Ruby on Rails
+
+You can load the Railtie that comes with the library into your Ruby 
+on Rails application by explicitly requiring it during the application startup:
+
+```ruby
+# In config/application.rb
+require "google/cloud/error_reporting/rails"
+```
+
+If you're using the `stackdriver` gem, it automatically loads the Railtie into 
+your application when it starts.
+
+### With other Rack-based frameworks
+
+Other Rack-based frameworks, such as Sinatra, can use the Rack Middleware 
+provided by the library:
 
-## Instrumentation Example
 ```ruby
 require "google/cloud/error_reporting"
- 
-# Configure Stackdriver ErrorReporting instrumentation
-Google::Cloud::ErrorReporting.configure do |config|
-  config.project_id = "my-project"
-  config.keyfile = "/path/to/keyfile.json"
-end
- 
-# Insert a Rack Middleware to report unhanded exceptions 
 use Google::Cloud::ErrorReporting::Middleware
- 
-# Or explicitly submit exceptions
+```
+
+## Reporting errors manually
+
+Manually reporting an error is as easy as calling the report method:
+
+```ruby
+require "google/cloud/error_reporting"
 begin
-  fail "Boom!"
+  fail "boom!"
 rescue => exception
   Google::Cloud::ErrorReporting.report exception
 end
 ```
 
-## Rails and Rack Integration
+## Configuring the library
+
+You can customize the behavior of the Stackdriver Error Reporting library for 
+Ruby. See the [configuration guide](../stackdriver/docs/configuration.md) for a list 
+of possible configuration options.
+
+## Running on Google Cloud Platform
+
+The Stackdriver Error Reporting library for Ruby should work without you 
+manually providing authentication credentials for instances running on Google 
+Cloud Platform, as long as the Stackdriver Error Reporting API access scope is 
+enabled on that instance.
+
+### App Engine
+
+On Google App Engine, the Stackdriver Error Reporting API access scope is 
+enabled by default, and the Stackdriver Error Reporting library for Ruby can 
+be used without providing credentials or a project ID.
+
+### Container Engine
+
+On Google Container Engine, you must explicitly add the `cloud-platform` OAuth 
+scope when creating the cluster:
+
+```sh
+$ gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform
+```
+
+You may also do this through the Google Cloud Platform Console. Select 
+**Enabled** in the **Cloud Platform** section of **Create a container cluster**.
+
+### Compute Engine
+
+For Google Compute Engine instances, you must explicitly enable the 
+`cloud-platform` access scope for each instance. When you create a new instance 
+through the Google Cloud Platform Console, you can do this under Identity and 
+API access: Use the Compute Engine default service account and select "Allow 
+full access to all Cloud APIs" under Access scopes.
+
+## Running locally and elsewhere
+
+To run the Stackdriver Error Reporting outside of Google Cloud Platform, you 
+must supply your GCP project ID and appropriate service account credentials 
+directly to the Stackdriver Error Reporting. This applies to running the 
+library on your own workstation, on your datacenter's computers, or on the VM 
+instances of another cloud provider. See the [Authentication 
+section](#authentication) for instructions on how to do so.
+
+## Authentication
+
+The Instrumentation client and API use Service Account credentials to connect 
+to Google Cloud services. When running on Google Cloud Platform environments, 
+the credentials will be discovered automatically. When running on other 
+environments the Service Account credentials can be specified by providing in 
+several ways.
+
+The best way to provide authentication information if you're using Ruby on Rails
+is through the Rails configuration interface:
 
-This library also provides a built-in Railtie for Ruby on Rails integration. To
- do this, simply add this line to config/application.rb:
 ```ruby
-require "google/cloud/error_reporting/rails"
+# in config/environments/*.rb
+Rails.application.configure do |config|
+  # Shared parameters
+  config.google_cloud.project_id = "your-project-id"
+  config.google_cloud.keyfile = "/path/to/key.json"
+  # Or Stackdriver Error Reporting specific parameters
+  config.google_cloud.error_reporting.project_id = "your-project-id"
+  config.google_cloud.error_reporting.keyfile = "/path/to/key.json"
+end
 ```
 
-Alternatively, check out the [stackdriver](../stackdriver) gem, which includes 
-this library and enables the Railtie by default.
+Other Rack-based applications that are loading the Rack Middleware directly or
+using the manually reporting interface can leverage the configration interface:
+ 
+```ruby
+require "google/cloud/error_reporting"
+Google::Cloud.configure do |config|
+  # Shared parameters
+  config.project_id = "your-project-id"
+  config.keyfile = "/path/to/key.json"
+  # Or Stackdriver Error Reporting specific parameters
+  config.error_reporting.project_id = "your-project-id"
+  config.error_reporting.keyfile = "/path/to/key.json"
+end
+```
 
-For Rack integration and more examples, see the
-[Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation).
+This library also supports the other authentication methods provided by the 
+`google-cloud-ruby` suite. Instructions and configuration options are covered 
+in the [Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-debugger/guides/authentication).
 
 ## Supported Ruby Versions
 

data/lib/google-cloud-error_reporting.rb

@@ -70,11 +70,12 @@ module Google
     # 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 Google Cloud Platform project identifier for the
-    #   Stackdriver Error Reporting service you are connecting to. Use
-    #   Project.default_project if not provided.
-    # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-    #   file path the file must be readable.
+    # @param [String] project_id Google Cloud Platform project identifier for
+    #   the Stackdriver Error Reporting service you are connecting to. If not
+    #   present, the default project for the credentials is used.
+    # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+    #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+    #   Google::Auth::Credentials object. (See {ErrorReporting::Credentials})
     # @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
@@ -102,10 +103,11 @@ module Google
     #                                             service_version: "v8"
     #   error_reporting.report error_event
     #
-    def self.error_reporting project = nil, keyfile = nil, scope: nil,
+    def self.error_reporting project_id = nil, credentials = nil, scope: nil,
                              timeout: nil, client_config: nil
       require "google/cloud/error_reporting"
-      Google::Cloud::ErrorReporting.new project: project, keyfile: keyfile,
+      Google::Cloud::ErrorReporting.new project_id: project_id,
+                                        credentials: credentials,
                                         scope: scope, timeout: timeout,
                                         client_config: client_config
     end

data/lib/google/cloud/error_reporting.rb

@@ -91,10 +91,12 @@ module Google
       # [Authentication
       # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication).
       #
-      # @param [String] project Project identifier for the Stackdriver Error
-      #   Reporting service.
-      # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-      #   file path the file must be readable.
+      # @param [String] project_id Google Cloud Platform project identifier for
+      #   the Stackdriver Error Reporting service you are connecting to. If not
+      #   present, the default project for the credentials is used.
+      # @param [String, Hash, Google::Auth::Credentials] credentials The path to
+      #   the keyfile as a String, the contents of the keyfile as a Hash, or a
+      #   Google::Auth::Credentials object. (See {ErrorReporting::Credentials})
       # @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
@@ -107,6 +109,9 @@ module Google
       # @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.
+      # @param [String] project Alias for the `project_id` argument. Deprecated.
+      # @param [String] keyfile Alias for the `credentials` argument.
+      #   Deprecated.
       #
       # @return [Google::Cloud::ErrorReporting::Project]
       #
@@ -116,19 +121,23 @@ module Google
       #   error_reporting = Google::Cloud::ErrorReporting.new
       #   # ...
       #
-      def self.new project: nil, keyfile: nil, scope: nil, timeout: nil,
-                   client_config: nil
-        project ||= Google::Cloud::ErrorReporting::Project.default_project
-        project = project.to_s
-        fail ArgumentError, "project is missing" if project.empty?
+      def self.new project_id: nil, credentials: nil, scope: nil, timeout: nil,
+                   client_config: nil, project: nil, keyfile: nil
+        project_id ||= (project || ErrorReporting::Project.default_project_id)
+        project_id = project_id.to_s
+        fail ArgumentError, "project_id is missing" if project_id.empty?
 
-        credentials =
-          Google::Cloud::ErrorReporting::Credentials.credentials_with_scope(
-            keyfile, scope)
+        credentials ||= keyfile
+        credentials ||= ErrorReporting::Credentials.default(scope: scope)
+        unless credentials.is_a? Google::Auth::Credentials
+          credentials = ErrorReporting::Credentials.new credentials,
+                                                        scope: scope
+        end
 
-        Google::Cloud::ErrorReporting::Project.new(
-          Google::Cloud::ErrorReporting::Service.new(
-            project, credentials, timeout: timeout, client_config: client_config
+        ErrorReporting::Project.new(
+          ErrorReporting::Service.new(
+            project_id, credentials, timeout: timeout,
+                                     client_config: client_config
           )
         )
       end
@@ -147,7 +156,7 @@ module Google
       #   require "google/cloud/error_reporting"
       #
       #   Google::Cloud::ErrorReporting.configure do |config|
-      #     config.project_id = "my-project-id"
+      #     config.project_id = "my-project"
       #     config.keyfile = "/path/to/keyfile.json"
       #     config.service_name = "my-service"
       #     config.service_version = "v8"

data/lib/google/cloud/error_reporting/credentials.rb

@@ -13,28 +13,44 @@
 # limitations under the License.
 
 
-require "google/cloud/credentials"
+require "googleauth"
 
 module Google
   module Cloud
     module ErrorReporting
       ##
-      # @private Represents the OAuth 2.0 signing logic for ErrorReporting.
-      class Credentials < Google::Cloud::Credentials
+      # # Credentials
+      #
+      # Represents the authentication and authorization used to connect to the
+      # Stackdriver Error Reporting service.
+      #
+      # @example
+      #   require "google/cloud/error_reporting"
+      #
+      #   keyfile = "/path/to/keyfile.json"
+      #   creds = Google::Cloud::ErrorReporting::Credentials.new keyfile
+      #
+      #   error_reporting = Google::Cloud::ErrorReporting.new(
+      #     project_id: "my-project",
+      #     credentials: creds
+      #   )
+      #
+      #   error_reporting.project_id #=> "my-project"
+      #
+      class Credentials < Google::Auth::Credentials
         SCOPE = ["https://www.googleapis.com/auth/cloud-platform"]
-        PATH_ENV_VARS = %w(ERROR_REPORTING_KEYFILE GOOGLE_CLOUD_KEYFILE)
-        JSON_ENV_VARS =
-          %w(ERROR_REPORTING_KEYFILE_JSON GOOGLE_CLOUD_KEYFILE_JSON)
-
-        ##
-        # @private Create credentials with given scope and/or keyfile.
-        def self.credentials_with_scope keyfile, scope = nil
-          if keyfile.nil?
-            default(scope: scope)
-          else
-            new(keyfile, scope: scope)
-          end
-        end
+        PATH_ENV_VARS = %w(ERROR_REPORTING_CREDENTIALS
+                           GOOGLE_CLOUD_CREDENTIALS
+                           ERROR_REPORTING_KEYFILE
+                           GOOGLE_CLOUD_KEYFILE
+                           GCLOUD_KEYFILE)
+        JSON_ENV_VARS = %w(ERROR_REPORTING_CREDENTIALS_JSON
+                           GOOGLE_CLOUD_CREDENTIALS_JSON
+                           ERROR_REPORTING_KEYFILE_JSON
+                           GOOGLE_CLOUD_KEYFILE_JSON
+                           GCLOUD_KEYFILE_JSON)
+        DEFAULT_PATHS = \
+          ["~/.config/gcloud/application_default_credentials.json"]
       end
     end
   end

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

@@ -171,8 +171,9 @@ module Google
         ##
         # Fallback to default configuration values if not defined already
         def init_default_config
-          configuration.project_id ||= Cloud.configure.project_id ||
-                                       ErrorReporting::Project.default_project
+          configuration.project_id ||= \
+            (Cloud.configure.project_id ||
+             ErrorReporting::Project.default_project_id)
           configuration.keyfile ||= Cloud.configure.keyfile
           configuration.service_name ||=
             ErrorReporting::Project.default_service_name

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

@@ -50,11 +50,14 @@ module Google
         #
         # @return [String] default valid GCP project_id
         #
-        def self.default_project
+        def self.default_project_id
           ENV["ERROR_REPORTING_PROJECT"] ||
             ENV["GOOGLE_CLOUD_PROJECT"] ||
             Google::Cloud.env.project_id
         end
+        class << self
+          alias_method :default_project, :default_project_id
+        end
 
         ##
         # Find default service_name from `ERROR_REPORTING_SERVICE`,
@@ -102,9 +105,10 @@ module Google
         #
         # @return [String] The current project_id
         #
-        def project
+        def project_id
           service.project
         end
+        alias_method :project, :project_id
 
         ##
         # Report a {Google::Cloud::ErrorReporting::ErrorEvent} to Stackdriver

data/lib/google/cloud/error_reporting/rails.rb

@@ -121,7 +121,7 @@ module Google
         # Fallback to default config values if config parameters not provided.
         def self.init_default_config
           config = ErrorReporting.configure
-          config.project_id ||= ErrorReporting::Project.default_project
+          config.project_id ||= ErrorReporting::Project.default_project_id
           config.service_name ||= ErrorReporting::Project.default_service_name
           config.service_version ||=
             ErrorReporting::Project.default_service_version
@@ -129,9 +129,15 @@ module Google
 
         ##
         # @private Verify credentials
-        def self.valid_credentials? project_id, keyfile
+        def self.valid_credentials? project_id, credentials
           begin
-            ErrorReporting::Credentials.credentials_with_scope keyfile
+            # if credentials is nil, get default
+            credentials ||= ErrorReporting::Credentials.default(scope: scope)
+            # only create a new Credentials object if the val isn't one already
+            unless credentials.is_a? Google::Auth::Credentials
+              # if credentials is not a Credentials object, create one
+              ErrorReporting::Credentials.new credentials, scope: scope
+            end
           rescue => e
             STDOUT.puts "Note: Google::Cloud::ErrorReporting is disabled " \
               "because it failed to authorize with the service. (#{e.message})"