google-cloud-error_reporting 0.21.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5600f55b4c5304420859f9c425895392f0e8f8e9
+  data.tar.gz: cb684753b01da03c48ca26056318635ecddf65ec
+SHA512:
+  metadata.gz: 8b0ccadbb064b195a2a9c40f4dd97a822c01bfd2932b2dc9a792e416c3763ae52c1940180870409845db7102b765cbcce397b5ad0398108a2506d5710e34fcff
+  data.tar.gz: 67b194caaecf90cc12912fc8b2c178e19a67187579a9ac99d546562324d7e4439ce2a5a7807a2668b06baf6f3a1880d14d57e7d06f3ecf7b1fb7b813277d45c2

data/README.md

@@ -0,0 +1,82 @@
+Stackdriver Clouderrorreporting API for Ruby
+=================================================
+
+google-cloud-error_reporting uses [Google API extensions][google-gax] to provide an
+easy-to-use client library for the [Stackdriver Clouderrorreporting API][] (v1beta1) defined in the [googleapis][] git repository
+
+
+[googleapis]: https://github.com/googleapis/googleapis/tree/master/google/google/devtools/clouderrorreporting/v1beta1
+[google-gax]: https://github.com/googleapis/gax-ruby
+[Stackdriver Clouderrorreporting API]: https://developers.google.com/apis-explorer/#p/clouderrorreporting/v1beta1/
+
+Getting started
+---------------
+
+google-cloud-error_reporting will allow you to connect to the [Stackdriver Clouderrorreporting API][] and access all its methods.
+
+In order to achieve so you need to set up authentication as well as install the library locally.
+
+
+Setup Authentication
+--------------------
+
+To authenticate all your API calls, first install and setup the [Google Cloud SDK][].
+Once done, you can then run the following command in your terminal:
+
+    $ gcloud beta auth application-default login
+
+or
+
+    $ gcloud auth login
+
+Please see [[gcloud beta auth application-default login][] document for the difference between these commands.
+
+[Google Cloud SDK]: https://cloud.google.com/sdk/
+[gcloud beta auth application-default login]: https://cloud.google.com/sdk/gcloud/reference/beta/auth/application-default/login
+
+
+Installation
+-------------------
+
+Install this library using gem:
+
+    $ [sudo] gem install google-cloud-error_reporting
+    
+
+Rails Integration
+---------------
+
+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"
+```
+Then the library can be configured through this set of Rails parameters in config/environments/*.rb:
+```ruby
+# Sharing authentication parameters
+config.google_cloud.project_id = "gcp-project-id"
+config.google_cloud.keyfile = "/path/to/gcp/secret.json"
+# Or more specificly for ErrorReporting
+config.google_cloud.error_reporting.project_id = "gcp-project-id"
+config.google_cloud.error_reporting.keyfile = "/path/to/gcp/sercret.json"
+ 
+# Explicitly enable or disable ErrorReporting
+config.google_cloud.use_error_reporting = true
+ 
+# Set Stackdriver Error Reporting service context
+config.google_cloud.error_reporting.service_name = "my-app-name"
+config.google_cloud.error_reporting.service_version = "my-app-version"
+```
+
+Alternatively, check out [stackdriver](../stackdriver) gem, which includes this Railtie by default.
+
+Rack Integration
+---------------
+
+Other Rack base framework can also directly leverage the built-in Middleware.
+```ruby
+require "google/cloud/error_reporting/v1beta1"
+
+use Google::Cloud::ErrorReporting::Middleware
+```
+
+At this point you are all set to continue.

data/Rakefile

@@ -0,0 +1,72 @@
+# 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 "bundler/setup"
+require "bundler/gem_tasks"
+
+task :test do
+  $LOAD_PATH.unshift "lib", "test"
+  Dir.glob("test/**/*_test.rb").each { |file| require_relative file }
+end
+
+task :rubocop do
+end
+
+namespace :test do
+  desc "Runs tests with coverage."
+  task :coverage do
+  end
+end
+
+# Acceptance tests
+desc "Runs the error_reporting acceptance tests."
+task :acceptance, :project, :keyfile do |_, args|
+end
+
+namespace :acceptance do
+  desc "Runs acceptance tests with coverage."
+  task :coverage, :project, :keyfile do |t, args|
+  end
+
+
+  desc "Runs acceptance cleanup."
+  task :cleanup do
+  end
+end
+
+desc "Runs yard-doctest example tests."
+task :doctest do
+end
+
+desc "Start an interactive shell."
+task :console do
+end
+
+require "yard"
+require "yard/rake/yardoc_task"
+YARD::Rake::YardocTask.new
+
+desc "Generates JSON output from google-cloud-error_reporting .yardoc"
+task :jsondoc => :yard do
+  require "rubygems"
+  require "gcloud/jsondoc"
+
+  registry = YARD::Registry.load! ".yardoc"
+  generator = Gcloud::Jsondoc::Generator.new registry, "google-cloud-error_reporting"
+  generator.write_to "jsondoc"
+  cp ["docs/toc.json"], "jsondoc", verbose: true
+end
+
+task :default => :test

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

@@ -0,0 +1,242 @@
+# 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 "rack"
+require "rack/request"
+
+module Google
+  module Cloud
+    module ErrorReporting
+      ##
+      # Middleware
+      #
+      # Google::Cloud::ErrorReporting::Middleware defines a Rack Middleware
+      # that can automatically catch upstream exceptions and report them
+      # to Stackdriver Error Reporting.
+      #
+      class Middleware
+        attr_reader :error_reporting, :ignore_classes, :project_id,
+                    :service_name, :service_version
+
+        ##
+        # Construct a new instance of Middleware
+        #
+        # @param [Rack Application] app The Rack application
+        # @param [Google::Cloud::ErrorReporting::V1beta1::ReportErrorsServiceApi]
+        #   error_reporting A ErrorReporting::V1beta1::ReportErrorsServiceApi
+        #   object to for reporting exceptions
+        # @param [String] project_id Name of GCP project. Default to
+        #   ENV["ERROR_REPORTING_PROJECT"] then ENV["GOOGLE_CLOUD_PROJECT"].
+        #   Automatically discovered if on GAE
+        # @param [String] service_name Name of the service. Default to
+        #   ENV["ERROR_REPORTING_SERVICE"] then "ruby". Automatically discovered
+        #   if on GAE
+        # @param [String] service_version Version of the service. Optional.
+        #   ENV["ERROR_REPORTING_VERSION"]. Automatically discovered if on GAE
+        # @param [Array<Class>] ignore_classes A single or an array of Exception
+        #   classes to ignore
+        #
+        # @return A new instance of Middleware
+        #
+        def initialize app, error_reporting: nil, project_id: nil,
+                       service_name: nil, service_version: nil,
+                       ignore_classes: nil
+          @app = app
+          @error_reporting = error_reporting ||
+            Google::Cloud::ErrorReporting::V1beta1::ReportErrorsServiceApi.new
+
+          @service_name = service_name ||
+                          ENV["ERROR_REPORTING_SERVICE"] ||
+                          Google::Cloud::Core::Environment.gae_module_id ||
+                          "ruby"
+          @service_version = service_version ||
+                             ENV["ERROR_REPORTING_VERSION"] ||
+                             Google::Cloud::Core::Environment.gae_module_version
+          @ignore_classes = Array(ignore_classes)
+          @project_id = project_id ||
+                        ENV["ERROR_REPORTING_PROJECT"] ||
+                        ENV["GOOGLE_CLOUD_PROJECT"] ||
+                        Google::Cloud::Core::Environment.project_id
+
+          raise ArgumentError, "project_id is required" if @project_id.nil?
+        end
+
+        ##
+        # Implements the mandatory Rack Middleware call method.
+        #
+        # Catch all Exceptions from upstream and report them to Stackdriver
+        # Error Reporting. Unless the exception's class is defined to be ignored
+        # by this Middleware.
+        #
+        # @param [Hash] env Rack environment hash
+        #
+        def call env
+          response = @app.call env
+
+          # sinatra doesn't always raise the Exception, but it saves it in
+          # env['sinatra.error']
+          if env["sinatra.error"].is_a? Exception
+            report_exception env, env["sinatra.error"]
+          end
+
+          response
+        rescue Exception => exception
+          report_exception env, exception
+
+          # Always raise exception backup
+          raise exception
+        end
+
+        ##
+        # Report an given exception to Stackdriver Error Reporting.
+        #
+        # While it reports most of the exceptions. Certain Rails exceptions that
+        # maps to a HTTP status code less than 500 will be treated as not the
+        # app fault and ignored.
+        #
+        # @param [Hash] env Rack environment hash
+        # @param [Exception] exception The Ruby exception to report.
+        #
+        def report_exception env, exception
+          # Do not any exceptions that's specified by the ignore_classes list.
+          return if ignore_classes.include? exception.class
+
+          error_event = build_error_event_from_exception env,
+                                                         exception
+
+          # If this exception maps to a HTTP status code less than 500, do
+          # not report it.
+          return if
+            error_event.context.http_request.response_status_code.to_i < 500
+
+          error_reporting.report_error_event full_project_id, error_event
+        end
+
+        ##
+        # Creates a GRPC ErrorEvent based on the exception. Fill in the
+        # HttpRequestContext section of the ErrorEvent based on the HTTP Request
+        # headers.
+        #
+        # When used in Rails environment. It replies on
+        # ActionDispatch::ExceptionWrapper class to derive a HTTP status code
+        # based on the exception's class.
+        #
+        # @param [Hash] env Rack environment hash
+        # @param [Exception] exception Exception to convert from
+        #
+        # @return [Google::Devtools::Clouderrorreporting::V1beta1::ReportedErrorEvent]
+        #   The gRPC ReportedErrorEvent object that's based on given exception
+        #
+        def build_error_event_from_exception env, exception
+          # Build service_context hash
+          service_context = {
+                              service: service_name,
+                              version: service_version
+                            }.delete_if { |k,v| v.nil? }
+
+          # Build error message and source_location hash
+          if exception.backtrace.nil? || exception.backtrace.empty?
+            message = exception.message
+            report_location = nil
+          else
+            message = "#{exception.backtrace.first}: #{exception.message} " \
+                      "(#{exception.class})\n\t" +
+                      exception.backtrace.drop(1).join("\n\t")
+            file_path, line_number, function_name =
+              exception.backtrace.first.split(":")
+            function_name = function_name.to_s[/`(.*)'/, 1]
+            report_location = {
+                                file_path: file_path,
+                                function_name: function_name,
+                                line_number: line_number.to_i
+                              }.delete_if { |k,v| v.nil? }
+          end
+
+          # Build http_request_context hash
+          rack_request = Rack::Request.new env
+          http_method = rack_request.request_method
+          http_url = rack_request.url
+          http_user_agent = rack_request.user_agent
+          http_referrer = rack_request.referrer
+          http_status = get_http_status exception
+          http_remote_ip = rack_request.ip
+          http_request_context = {
+                                   method: http_method,
+                                   url: http_url,
+                                   user_agent: http_user_agent,
+                                   referrer: http_referrer,
+                                   response_status_code: http_status,
+                                   remote_ip: http_remote_ip
+                                 }.delete_if { |k,v| v.nil? }
+
+          # Build error_context hash
+          error_context = {
+                            http_request: http_request_context,
+                            user: ENV["USER"],
+                            report_location: report_location,
+                          }.delete_if { |k,v| v.nil? }
+
+          # Build error_event hash
+          t = Time.now
+          error_event = {
+            event_time: {
+              seconds: t.to_i,
+              nanos: t.nsec
+            },
+            service_context: service_context,
+            message: message,
+            context: error_context
+          }.delete_if { |k,v| v.nil? }
+
+          # Finally build and return GRPC ErrorEvent
+          Google::Devtools::Clouderrorreporting::V1beta1::ReportedErrorEvent.decode_json \
+            error_event.to_json
+        end
+
+        ##
+        # Build full ReportErrorsServiceApi project_path from project_id, which
+        # is in "projects/#{project_id}" format.
+        def full_project_id
+          Google::Cloud::ErrorReporting::V1beta1::ReportErrorsServiceApi.project_path project_id
+        end
+
+        private
+
+        ##
+        # Helper method to derive HTTP status code base on exception class in
+        # Rails. Returns nil if not in Rails environment
+        #
+        # @param [Exception] exception An Ruby exception
+        #
+        # @return [Integer] A number that represents HTTP status code or nil if
+        #   status code can't be determined
+        #
+        def get_http_status exception
+          http_status = nil
+          if defined?(ActionDispatch::ExceptionWrapper) &&
+             ActionDispatch::ExceptionWrapper.respond_to?(
+               :status_code_for_exception
+             )
+            http_status =
+              ActionDispatch::ExceptionWrapper.status_code_for_exception(
+                exception.class.name
+              )
+          end
+
+          http_status
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,173 @@
+# 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 "google/cloud/error_reporting/v1beta1"
+require "google/cloud/credentials"
+
+module Google
+  module Cloud
+    module ErrorReporting
+      ##
+      # Railtie
+      #
+      # Google::Cloud::ErrorReporting::Railtie automatically add the
+      # 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.
+      #
+      # 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"
+      #
+      class Railtie < ::Rails::Railtie
+        config.google_cloud = ActiveSupport::OrderedOptions.new unless
+                                config.respond_to? :google_cloud
+        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 ||
+              error_reporting.class.default_service_name
+            service_version = er_config.service_version ||
+              error_reporting.class.default_service_version
+
+            error_reporting =
+              Google::Cloud::ErrorReporting::V1beta1::ReportErrorsServiceApi.new channel: channel,
+                                                                                 app_name: service_name,
+                                                                                 app_version: service_version
+
+            # 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,
+                                        Google::Cloud::ErrorReporting::Middleware,
+                                        project_id: project_id,
+                                        error_reporting: error_reporting,
+                                        service_name: service_name,
+                                        service_version: service_version
+          end
+        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 = Google::Cloud::ErrorReporting::V1beta1::ReportErrorsServiceApi::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 = Google::Cloud::ErrorReporting::V1beta1::ReportErrorsServiceApi::SERVICE_ADDRESS
+
+          GRPC::Core::Channel.new host, nil, channel_cred
+        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.
+        #
+        # @param config The Rails.application.config
+        #
+        # @return true or false
+        #
+        def self.use_error_reporting? config
+          gcp_config = 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
+
+          # Check credentialing. Returns false if authorization errors are
+          # rescued.
+          keyfile = er_config.keyfile || gcp_config.keyfile
+          begin
+            grpc_channel keyfile
+          rescue Exception => e
+            Rails.logger.warn "Google::Cloud::ErrorReporting is not " \
+            "activated due to authorization error: #{e.message}"
+            return false
+          end
+
+          project_id = er_config.project_id ||
+                       gcp_config.project_id ||
+                       ENV["ERROR_REPORTING_PROJECT"] ||
+                       ENV["GOOGLE_CLOUD_PROJECT"] ||
+                       Google::Cloud::Core::Environment.project_id
+          if project_id.to_s.empty?
+            Rails.logger.warn "Google::Cloud::ErrorReporting is not " \
+            "activated due to empty project_id"
+            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)
+        end
+      end
+    end
+  end
+end