google-cloud-error_reporting 0.24.0 → 0.25.0

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

@@ -0,0 +1,224 @@
+# Copyright 2017 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 "google/cloud/errors"
+require "google/cloud/env"
+require "google/cloud/error_reporting/service"
+require "google/cloud/error_reporting/credentials"
+require "google/cloud/error_reporting/error_event"
+
+module Google
+  module Cloud
+    module ErrorReporting
+      ##
+      # Project
+      #
+      # Projects are top-level containers in Google Cloud Platform. They store
+      # information about billing and authorized users, and they control access
+      # to Stackdriver ErrorReporting. Each project has a friendly name and a
+      # unique ID. Projects can be created only in the [Google Developers
+      # Console](https://console.developers.google.com).
+      #
+      # @example
+      #   require "google/cloud/error_reporting"
+      #
+      #   error_reporting = Google::Cloud::ErrorReporting.new
+      #   error_event = error_reporting.error_event "Error with Backtrace",
+      #                                             timestamp: Time.now
+      #                                             service_name: "my_app_name"
+      #   error_reporting.report error_event
+      #
+      # See {Google::Cloud::ErrorReporting.new}
+      #
+      class Project
+        ##
+        # Find default project_id from `ERROR_REPORTING_RPOJECT`,
+        # `GOOGLE_CLOUD_PROJECT`, `GCLOUD_PROJECT` environment varaibles, or
+        # query from GCE meta service.
+        #
+        # @return [String] default valid GCP project_id
+        #
+        def self.default_project
+          ENV["ERROR_REPORTING_PROJECT"] ||
+            ENV["GOOGLE_CLOUD_PROJECT"] ||
+            Google::Cloud.env.project_id
+        end
+
+        ##
+        # Find default service_name from `ERROR_REPORTING_SERVICE`,
+        # `GAE_MODULE_NAME` environment Variables, or just "ruby".
+        #
+        # @return [String] default GCP service_name
+        #
+        def self.default_service_name
+          ENV["ERROR_REPORTING_SERVICE"] ||
+            Google::Cloud.env.app_engine_service_id ||
+            "ruby"
+        end
+
+        ##
+        # Find default service_version from `ERROR_REPORTING_VERSION` or
+        # `GAE_MODULE_VERSION` environment varaibles.
+        #
+        # @return [String] default GCP service_version
+        #
+        def self.default_service_version
+          ENV["ERROR_REPORTING_VERSION"] ||
+            Google::Cloud.env.app_engine_service_version
+        end
+
+        ##
+        # @private The Service object
+        attr_accessor :service
+
+        ##
+        # @private Create a new Project instance.
+        #
+        # @param [Google::Cloud::ErrorReporting::Service] service The underlying
+        #   Service object
+        #
+        # @return [Google::Cloud::ErrorReporting::Project] A new Project
+        #   instance
+        #
+        def initialize service
+          @service = service
+        end
+
+        ##
+        # Get the name of current project_id from underneath gRPC Service
+        # object.
+        #
+        # @return [String] The current project_id
+        #
+        def project
+          service.project
+        end
+
+        ##
+        # Report a {Google::Cloud::ErrorReporting::ErrorEvent} to Stackdriver
+        # Error Reporting service.
+        #
+        # @example
+        #   require "google/cloud/error_reporting"
+        #
+        #   error_reporting = Google::Cloud::ErrorReporting.new
+        #
+        #   error_event = error_reporting.error_event "Error with Backtrace"
+        #   error_reporting.report error_event
+        #
+        def report *args, &block
+          service.report *args, &block
+        end
+
+        ##
+        # Create a {Google::Cloud::ErrorReporting::ErrorEvent} from the
+        # given exception, and report this ErrorEvent to Stackdriver Error
+        # Reporting service.
+        #
+        # @param [Exception] exception A Ruby exception
+        # @param [String] service_name The service's name.
+        #   Default to {default_service_name}
+        # @param [String] service_version The service's version.
+        #   Default to {default_service_version}
+        #
+        # @example
+        #   require "google/cloud/error_reporting"
+        #
+        #   error_reporting = Google::Cloud::ErrorReporting.new
+        #
+        #   begin
+        #     fail StandardError, "A serious problem"
+        #   rescue StandardError => exception
+        #     error_reporting.report_exception, service_name: "my_app_name",
+        #                                       service_version: "v8"
+        #   end
+        #
+        def report_exception exception, service_name: nil, service_version: nil
+          error_event = ErrorEvent.from_exception exception
+
+          error_event.service_name =
+            service_name || self.class.default_service_name
+          error_event.service_version =
+            service_version || self.class.default_service_version
+
+          yield error_event if block_given?
+
+          report error_event
+        end
+
+        ##
+        # Create a new {Google::Cloud::ErrorReporting::ErrorEvent} instance
+        # with given parameters.
+        #
+        # @param [String] message The error message along with backtrace
+        # @param [String] service_name The service's name.
+        #   Default to {default_service_name}
+        # @param [String] service_version The service's version.
+        #   Default to {default_service_version}
+        # @param [Time] event_time Time when the event occurred. If not
+        #   provided, the time when the event was received by the Error
+        #   Reporting system will be used.
+        # @param [String] user The user who caused or was affected by the crash.
+        #   This can be a user ID, an email address, or an arbitrary token that
+        #   uniquely identifies the user. When sending an error report, leave
+        #   this field empty if the user was not logged in. In this case the
+        #   Error Reporting system will use other data, such as remote IP
+        #   address, to distinguish affected users.
+        # @param [String] file_path The source code filename, which can include
+        #   a truncated relative path, or a full path from a production machine.
+        # @param [Number] line_number 1-based. 0 indicates that the line number
+        #   is unknown.
+        # @param [String] function_name Human-readable name of a function or
+        #   method. The value can include optional context like the class or
+        #   package name. For example, my.package.MyClass.method in case of
+        #   Java.
+        #
+        # @return [ErrorEvent] A new ErrorEvent instance
+        #
+        # @example
+        #   require "google/cloud/error_reporting"
+        #
+        #   error_reporting = Google::Cloud::ErrorReporting.new
+        #
+        #   error_event =
+        #     error_reporting.error_event "Error Message with Backtrace",
+        #                                 event_time: Time.now,
+        #                                 service_name: "my_app_name",
+        #                                 service_version: "v8",
+        #                                 user: "johndoh",
+        #                                 file_path: "MyController.rb",
+        #                                 line_number: 123,
+        #                                 function_name: "index"
+        #   error_reporting.report error_event
+        #
+        def error_event message = nil, service_name: nil, service_version: nil,
+                        event_time: nil, user: nil, file_path: nil,
+                        line_number: nil, function_name: nil
+          ErrorEvent.new.tap do |e|
+            e.message = message
+            e.event_time = event_time
+            e.service_name = service_name || self.class.default_service_name
+            e.service_version = service_version ||
+                                self.class.default_service_version
+            e.user = user
+            e.file_path = file_path
+            e.line_number = line_number
+            e.function_name = function_name
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,4 +1,4 @@
-# Copyright 2016 Google Inc. All rights reserved.
+# Copyright 2017 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.
@@ -13,38 +13,30 @@
 # limitations under the License.
 
 
-require "google/cloud/env"
-require "google/cloud/error_reporting/v1beta1"
-require "google/cloud/error_reporting/middleware"
-require "google/cloud/credentials"
+require "google/cloud/error_reporting"
 
 module Google
   module Cloud
     module ErrorReporting
       ##
-      # Railtie
+      # # Railtie
       #
       # Google::Cloud::ErrorReporting::Railtie automatically add the
-      # Google::Cloud::ErrorReporting::Middleware to Rack in a Rails
+      # {Google::Cloud::ErrorReporting::Middleware} to Rack in a Rails
       # environment. It will automatically capture Exceptions from the Rails app
-      # and report them to Stackdriver Error Reporting.
+      # and report them to the Stackdriver Error Reporting service.
       #
       # The Middleware is only added when certain conditions are met. See
       # {Railtie.use_error_reporting?} for detail.
       #
-      # When loaded, the Google::Cloud::ErrorReporting::Middleware will be
-      # inserted after ::ActionDispatch::DebugExceptions Middleware, which
-      # allows it to actually rescue all Exceptions and throw it back up. The
-      # middleware should also be initialized with correct gcp project_id,
-      # keyfile, service_name, and service_version if they are defined in
-      # Rails environment files as follow:
-      #   config.google_cloud.project_id = "my-gcp-project"
-      #   config.google_cloud.keyfile = "/path/to/secret.json"
-      # or
-      #   config.google_cloud.error_reporting.project_id = "my-gcp-project"
-      #   config.google_cloud.error_reporting.keyfile = "/path/to/secret.json"
-      #   config.google_cloud.error_reporting.service_name = "my-service-name"
-      #   config.google_cloud.error_reporting.service_version = "v1"
+      # When loaded, the {Google::Cloud::ErrorReporting::Middleware} will be
+      # inserted after ActionDispatch::DebugExceptions or
+      # ActionDispatch::ShowExceptions Middleware, which allows it to intercept
+      # and handle all Exceptions without interfering with Rails's normal error
+      # pages.
+      # See the [Configuration
+      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver/guides/instrumentation_configuration)
+      # on how to configure the Railtie and Middleware.
       #
       class Railtie < ::Rails::Railtie
         config.google_cloud = ActiveSupport::OrderedOptions.new unless
@@ -52,134 +44,112 @@ module Google
         config.google_cloud.error_reporting = ActiveSupport::OrderedOptions.new
 
         initializer "Google.Cloud.ErrorReporting" do |app|
-          if self.class.use_error_reporting? app.config
-            gcp_config = app.config.google_cloud
-            er_config = gcp_config.error_reporting
-
-            project_id = er_config.project_id || gcp_config.project_id
-            keyfile = er_config.keyfile || gcp_config.keyfile
-
-            channel = self.class.grpc_channel keyfile
-            service_name = er_config.service_name
-            service_version = er_config.service_version
-
-            error_reporting = V1beta1::ReportErrorsServiceClient.new(
-              channel: channel
-            )
-
-            # In later versions of Rails, ActionDispatch::DebugExceptions is
-            # responsible for catching exceptions. But it didn't exist until
-            # Rails 3.2. So we use ShowExceptions as pivot for earlier Rails.
-            rails_exception_middleware =
-              if defined? ::ActionDispatch::DebugExceptions
-                ::ActionDispatch::DebugExceptions
-              else
-                ::ActionDispatch::ShowExceptions
-              end
-
-            app.middleware.insert_after rails_exception_middleware,
-                                        Middleware,
-                                        project_id: project_id,
-                                        error_reporting: error_reporting,
-                                        service_name: service_name,
-                                        service_version: service_version
-          end
+          self.class.consolidate_rails_config app.config
+
+          self.class.init_middleware app if Cloud.configure.use_error_reporting
         end
 
         ##
-        # Construct a gRPC Channel object from given keyfile
-        #
-        # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If
-        #   file path the file must be readable.
-        #
-        # @return [GRPC::Core::Channel] gRPC Channel object based on given
-        #   keyfile
-        #
-        def self.grpc_channel keyfile = nil
-          require "grpc"
-
-          scopes = V1beta1::ReportErrorsServiceClient::ALL_SCOPES
-          credentials = if keyfile.nil?
-                          Google::Cloud::Credentials.default(
-                            scope: scopes)
-                        else
-                          Google::Cloud::Credentials.new(
-                            keyfile, scope: scopes)
-                        end
-
-          # Return nil if :this_channel_is_insecure
-          return nil if credentials == :this_channel_is_insecure
-
-          channel_cred = GRPC::Core::ChannelCredentials.new.compose \
-            GRPC::Core::CallCredentials.new credentials.client.updater_proc
-          host = V1beta1::ReportErrorsServiceClient::SERVICE_ADDRESS
-
-          GRPC::Core::Channel.new host, nil, channel_cred
+        # @private Init Error Reporting integration for Rails. Setup
+        # configuration and insert the Middleware.
+        def self.init_middleware app
+          # In later versions of Rails, ActionDispatch::DebugExceptions is
+          # responsible for catching exceptions. But it didn't exist until
+          # Rails 3.2. So we use ShowExceptions as fallback for earlier Rails.
+          rails_exception_middleware =
+            if defined? ::ActionDispatch::DebugExceptions
+              ::ActionDispatch::DebugExceptions
+            else
+              ::ActionDispatch::ShowExceptions
+            end
+
+          app.middleware.insert_after rails_exception_middleware,
+                                      Google::Cloud::ErrorReporting::Middleware
         end
 
         ##
-        # Determine whether to use Stackdriver Error Reporting or not.
-        #
-        # Returns true if valid GCP project_id and keyfile are provided and
-        # either Rails is in "production" environment or \
-        # config.google_cloud.use_error_reporting is explicitly true. Otherwise
-        # false.
+        # @private Consolidate Rails configuration into Error Reporting
+        # instrumentation configuration. Also consolidate the
+        # `use_error_reporting` setting by verifying credentials and Rails
+        # environment. The `use_error_reporting` setting will be true if
+        # credentials are valid, and the setting is manually set to true or
+        # Rails is in production environment.
         #
         # @param [Rails::Railtie::Configuration] config The
         #   Rails.application.config
         #
-        # @return [Boolean] Whether to use Stackdriver Error Reporting
-        #
-        def self.use_error_reporting? config
-          gcp_config = config.google_cloud
+        def self.consolidate_rails_config config
+          merge_rails_config config
+
+          init_default_config
+
+          # Done if Google::Cloud.configure.use_error_reporting is explicitly
+          # false
+          return if Google::Cloud.configure.use_error_reporting == false
+
+          # Verify credentials and set use_error_reporting to false if
+          # credentials are invalid
+          unless valid_credentials? ErrorReporting.configure.project_id,
+                                    ErrorReporting.configure.keyfile
+            Cloud.configure.use_error_reporting = false
+            return
+          end
+
+          # Otherwise set use_error_reporting to true if Rails is running in
+          # production
+          Google::Cloud.configure.use_error_reporting ||= Rails.env.production?
+        end
+
+        ##
+        # @private Merge Rails configuration into Error Reporting
+        # instrumentation configuration.
+        def self.merge_rails_config rails_config
+          gcp_config = rails_config.google_cloud
           er_config = gcp_config.error_reporting
 
-          # Return false if config.google_cloud.use_error_reporting is
-          # explicitly false
-          return false if gcp_config.key?(:use_error_reporting) &&
-                          !gcp_config.use_error_reporting
+          Cloud.configure.use_error_reporting ||= gcp_config.use_error_reporting
+          ErrorReporting.configure do |config|
+            config.project_id ||= er_config.project_id || gcp_config.project_id
+            config.keyfile ||= er_config.keyfile || gcp_config.keyfile
+            config.service_name ||= er_config.service_name
+            config.service_version ||= er_config.service_version
+            config.ignore_classes ||= er_config.ignore_classes
+          end
+        end
 
-          # Check credentialing. Returns false if authorization errors are
-          # rescued.
-          keyfile = er_config.keyfile || gcp_config.keyfile
+        ##
+        # 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.service_name ||= ErrorReporting::Project.default_service_name
+          config.service_version ||=
+            ErrorReporting::Project.default_service_version
+        end
+
+        ##
+        # @private Verify credentials
+        def self.valid_credentials? project_id, keyfile
           begin
-            grpc_channel keyfile
-          rescue StandardError => e
-            Rails.logger.warn "Google::Cloud::ErrorReporting is not " \
-            "activated due to authorization error: #{e.message}"
+            ErrorReporting::Credentials.credentials_with_scope keyfile
+          rescue => e
+            STDOUT.puts "Note: Google::Cloud::ErrorReporting is disabled " \
+              "because it failed to authorize with the service. (#{e.message})"
             return false
           end
 
-          if project_id(config).to_s.empty?
-            Rails.logger.warn "Google::Cloud::ErrorReporting is not " \
-            "activated due to empty project_id"
+          if project_id.to_s.empty?
+            STDOUT.puts "Note: Google::Cloud::ErrorReporting is disabled " \
+              "because the project ID could not be determined."
             return false
           end
 
-          # Otherwise return true if Rails is running in production or
-          # config.google_cloud.use_error_reporting is explicitly true
-          Rails.env.production? ||
-            (gcp_config.key?(:use_error_reporting) &&
-              gcp_config.use_error_reporting)
+          true
         end
 
-        ##
-        # Determine the GCP project_id from Rails configuration or environment
-        # variables. Default to Google::Cloud.env.project_id
-        #
-        # @param [Rails::Railtie::Configuration] config The
-        #   Rails.application.config
-        #
-        # @return [String] GCP project_id
-        #
-        def self.project_id config
-          config.google_cloud.error_reporting.project_id ||
-            config.google_cloud.project_id ||
-            ENV["ERROR_REPORTING_PROJECT"] ||
-            ENV["GOOGLE_CLOUD_PROJECT"] ||
-            Google::Cloud.env.project_id
-        end
-        private_class_method :project_id
+        private_class_method :merge_rails_config,
+                             :init_default_config,
+                             :valid_credentials?
       end
     end
   end