google-cloud-error_reporting 0.24.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 09b2cd382fd915741f345c17f5f14d822bdfa5f7
-  data.tar.gz: 441052f69914747bb47c7dbf085ac4f89d3520a2
+  metadata.gz: 2f57b6c70aad426eb8b82902378418d095dcb7df
+  data.tar.gz: 68844ca432aa4fea4ccf1846928ba9ede67b175c
 SHA512:
-  metadata.gz: e02c93b66aaf87937656a5ae65f342b48cb2409863695870ba4eac0da9d315ebcff19ec6de433030c375eea4e3f2c6b47a0d6fe230c504df367a5c794c8e15cd
-  data.tar.gz: 6a8440e222cb88dde032a3366728fb7ee73802a5ef87b41ed70ac797287049d5fdaec3d8a7ab8f38e88c5669ec074dd09fcb49809eb54ac8d64b9f4fe4191c09
+  metadata.gz: 1fc21b526bdb71e683f6a17d8eea04ff90f19d5f16b4344de4ff9ad1e039ad0a0db5a45a7e5b2370d6ddc36a210d682f166e120bb2e0b6367fb35a91b5c600c5
+  data.tar.gz: 9d7b384e32d1c9b25b61305cd00d3c594db0d625ee94eeff1791c703bf3d023569a5844c3df5eaf59809d1948b358e9323cea9e0e40fdf9f8479aee7a0a9e800

data/README.md

@@ -1,82 +1,109 @@
-Stackdriver Error Reporting API for Ruby
-=================================================
-
-google-cloud-error_reporting uses [Google API extensions][google-gax] to provide an
-easy-to-use client library for the [Stackdriver Error Reporting API][] (v1beta1) defined in the [googleapis][] git repository
-
-
-[googleapis]: https://github.com/googleapis/googleapis/tree/master/google/devtools/clouderrorreporting/v1beta1
-[google-gax]: https://github.com/googleapis/gax-ruby
-[Stackdriver Error Reporting API]: https://developers.google.com/apis-explorer/#p/clouderrorreporting/v1beta1/
+# google-cloud-error_reporting
+
+[Stackdriver Error Reporting](https://cloud.google.com/error-reporting/) counts,
+analyzes and aggregates errors raised in your running cloud services. A
+centralized error management interface displays the results with sorting 
+and filtering capabilities. A dedicated view shows the error details: time 
+chart, occurrences, affected user count, first and last seen dates and a 
+cleaned exception stack trace. Opt-in to receive email and mobile alerts on 
+new errors.
+
+- [google-cloud-error_reporting API documentation](http://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/latest)
+- [google-cloud-error_reporting instrumentation documentation](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation)
+- [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
+```sh
+$ gem install google-cloud-error_reporting
+```
 
-Getting started
----------------
+## Authentication
 
-google-cloud-error_reporting will allow you to connect to the [Stackdriver Error Reporting API][] and access all its methods.
+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.
 
-In order to achieve so you need to set up authentication as well as install the library locally.
+Instructions and configuration options are covered in the 
+[Authentication Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/authentication).
 
+## 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
+begin
+  fail "Boom!"
+rescue => exception
+  Google::Cloud::ErrorReporting.report exception
+end
+```
 
-Setup Authentication
---------------------
+## Rails and Rack Integration
 
-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:
+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"
+```
 
-    $ gcloud beta auth application-default login
+Alternatively, check out the [stackdriver](../stackdriver) gem, which includes 
+this library and enables the Railtie by default.
 
-or
+For Rack integration and more examples, see the
+[Instrumentation Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation).
 
-    $ gcloud auth login
+## Supported Ruby Versions
 
-Please see [gcloud beta auth application-default login][] document for the difference between these commands.
+This library is supported on Ruby 2.0+.
 
-[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
+## Versioning
 
+This library follows [Semantic Versioning](http://semver.org/).
 
-Installation
--------------------
+It is currently in major version zero (0.y.z), which means that anything may 
+change at any time and the public API should not be considered stable.
 
-Install this library using gem:
+## Contributing
 
-    $ [sudo] gem install google-cloud-error_reporting
-    
+Contributions to this library are always welcome and highly encouraged.
 
-Rails Integration
----------------
+See the 
+[Contributing Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/contributing) 
+for more information on how to get started.
 
-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"
-```
+Please note that this project is released with a Contributor Code of Conduct. By
+participating in this project you agree to abide by its terms. See 
+[Code of Conduct](../CODE_OF_CONDUCT.md) for more information.
 
-Alternatively, check out [stackdriver](../stackdriver) gem, which includes this Railtie by default.
+## License
 
-Rack Integration
----------------
+This library is licensed under Apache 2.0. Full license text is available in
+ [LICENSE](LICENSE).
 
-Other Rack base framework can also directly leverage the built-in Middleware.
-```ruby
-require "google/cloud/error_reporting/v1beta1"
+## Support
 
-use Google::Cloud::ErrorReporting::Middleware
-```
+Please 
+[report bugs at the project on Github](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues).
+Don't hesitate to 
+[ask questions](http://stackoverflow.com/questions/tagged/google-cloud-platform+ruby) 
+about the client or APIs on [StackOverflow](http://stackoverflow.com).
 
-At this point you are all set to continue.

data/lib/google-cloud-error_reporting.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,12 +13,100 @@
 # limitations under the License.
 
 ##
-# This file is here to be autorequired by bundler, so that the .logging and
-# #logging methods can be available, but the library and all dependencies won't
-# be loaded until required and used.
+# This file is here to be autorequired by bundler
 
 
 gem "google-cloud-core"
 require "google/cloud"
 
-# There is no Google::Cloud integration to add.
+module Google
+  module Cloud
+    ##
+    # Create a new object for connecting to the Stackdriver Error Reporting
+    # service. Each call creates a new connection.
+    #
+    # For more information on connecting to Google Cloud see the [Authentication
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/guides/authentication)
+    #
+    # @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
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/cloud-platform`
+    # @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.
+    #
+    # @return [Google::Cloud::ErrorReporting::Project]
+    #
+    # @example
+    #   require "google/cloud/error_reporting"
+    #
+    #   gcloud = Google::Cloud.new "GCP_Project_ID",
+    #                              "/path/to/gcp/secretkey.json"
+    #   error_reporting = gcloud.error_reporting
+    #
+    #   error_event = error_reporting.error_event "Error with Backtrace",
+    #                                             timestamp: Time.now,
+    #                                             service_name: "my_app_name",
+    #                                             service_version: "v8"
+    #   error_reporting.report error_event
+    #
+    def error_reporting scope: nil, timeout: nil, client_config: nil
+      Google::Cloud.error_reporting @project, @keyfile,
+                                    scope: scope,
+                                    timeout: (timeout || @timeout),
+                                    client_config: client_config
+    end
+
+
+    ##
+    # Create a new object for connecting to the Stackdriver Error Reporting
+    # service. Each call creates a new connection.
+    #
+    # 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, 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
+    #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+    #
+    #   The default scope is:
+    #
+    #   * `https://www.googleapis.com/auth/cloud-platform`
+    # @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.
+    #
+    # @return [Google::Cloud::ErrorReporting::Project]
+    #
+    # @example
+    #   require "google/cloud/error_reporting"
+    #
+    #   gcloud = Google::Cloud.error_reporting "GCP_Project_ID",
+    #                                          "/path/to/gcp/secretkey.json"
+    #
+    #   error_event = error_reporting.error_event "Error with Backtrace",
+    #                                             timestamp: Time.now,
+    #                                             service_name: "my_app_name",
+    #                                             service_version: "v8"
+    #   error_reporting.report error_event
+    #
+    def self.error_reporting project = nil, keyfile = nil, scope: nil,
+                             timeout: nil, client_config: nil
+      require "google/cloud/error_reporting"
+      Google::Cloud::ErrorReporting.new project: project, keyfile: keyfile,
+                                        scope: scope, timeout: timeout,
+                                        client_config: client_config
+    end
+  end
+end

data/lib/google/cloud/error_reporting.rb

@@ -0,0 +1,238 @@
+# 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-error_reporting"
+require "google/cloud/error_reporting/project"
+require "google/cloud/error_reporting/middleware"
+require "stackdriver/core"
+
+module Google
+  module Cloud
+    ##
+    # # ErrorReporting
+    #
+    # Stackdriver Error Reporting counts, analyzes and aggregates the crashes in
+    # your running cloud services. The Stackdriver Error Reporting
+    # Instrumentation client provides
+    # [a simple way to report errors](#how-to-report-errors) from your
+    # application.
+    #
+    # For general information about Stackdriver Error Reporting, read
+    # [Stackdriver Error Reporting
+    # Documentation](https://cloud.google.com/error-reporting/docs/).
+    #
+    # The goal of google-cloud-ruby is to provide an API that is comfortable to
+    # Rubyists. Authentication is handled by the client. You can provide the
+    # project and credential information to connect to the Stackdriver Error
+    # Reporting service, or if you are running on Google Cloud Platform 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/google-cloud-ruby/#/docs/guides/authentication).
+    #
+    # ## How to report errors
+    #
+    # You can easily report exceptions from your applications to Stackdriver
+    # Error Reporting service:
+    #
+    # ```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
+    # begin
+    #   fail "Boom!"
+    # rescue => exception
+    #   Google::Cloud::ErrorReporting.report exception
+    # end
+    # ```
+    #
+    # See the [Instrumentation
+    # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/google-cloud-error_reporting/guides/instrumentation)
+    # for more examples.
+    #
+    module ErrorReporting
+      # Initialize :error_reporting as a nested Configuration under
+      # Google::Cloud if haven't already
+      unless Google::Cloud.configure.option? :error_reporting
+        Google::Cloud.configure.add_options :error_reporting
+      end
+
+      ##
+      # @private The default Google::Cloud::ErrorReporting::Project client used
+      # for the Google::Cloud::ErrorReporting.report API.
+      @@default_client = nil
+
+      ##
+      # Creates a new object for connecting to the Stackdriver Error Reporting
+      # service. Each call creates a new connection.
+      #
+      # 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 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, 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
+      #   APIs](https://developers.google.com/identity/protocols/OAuth2).
+      #
+      #   The default scope is:
+      #
+      #   * `https://www.googleapis.com/auth/cloud-platform`
+      #
+      # @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.
+      #
+      # @return [Google::Cloud::ErrorReporting::Project]
+      #
+      # @example
+      #   require "google/cloud/error_reporting"
+      #
+      #   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?
+
+        credentials =
+          Google::Cloud::ErrorReporting::Credentials.credentials_with_scope(
+            keyfile, scope)
+
+        Google::Cloud::ErrorReporting::Project.new(
+          Google::Cloud::ErrorReporting::Service.new(
+            project, credentials, timeout: timeout, client_config: client_config
+          )
+        )
+      end
+
+      ##
+      # Configure the default {Google::Cloud::ErrorReporting::Project}
+      # client, allows the {.report} public method to reuse these
+      # configured parameters.
+      #
+      # See the [Configuration
+      # Guide](https://googlecloudplatform.github.io/google-cloud-ruby/#/docs/stackdriver/guides/instrumentation_configuration)
+      # for full configuration parameters.
+      #
+      # @example
+      #   # in app.rb
+      #   require "google/cloud/error_reporting"
+      #
+      #   Google::Cloud::ErrorReporting.configure do |config|
+      #     config.project_id = "my-project-id"
+      #     config.keyfile = "/path/to/keyfile.json"
+      #     config.service_name = "my-service"
+      #     config.service_version = "v8"
+      #   end
+      #
+      #   begin
+      #     fail "boom"
+      #   rescue => exception
+      #     # Report exception using configuration parameters provided above
+      #     Google::Cloud::ErrorReporting.report exception
+      #   end
+      #
+      # @return [Stackdriver::Core::Configuration] The configuration object
+      #   the Google::Cloud::ErrorReporting module uses.
+      #
+      def self.configure
+        yield Google::Cloud.configure.error_reporting if block_given?
+
+        Google::Cloud.configure.error_reporting
+      end
+
+      ##
+      # Provides an easy-to-use interface to Report a Ruby exception object to
+      # Stackdriver ErrorReporting service. This method helps users to
+      # transform the Ruby exception into an Stackdriver ErrorReporting
+      # ErrorEvent gRPC structure, so users don't need to. This should be the
+      # prefered method to use when users wish to report captured exception in
+      # applications.
+      #
+      # This public method creates a default Stackdriver ErrorReporting client
+      # and reuse that between calls. The default client is initialized with
+      # parameters defined in {.configure}.
+      #
+      # The error event can be customized before reporting. See the example
+      # below and {Google::Cloud::ErrorReporting::ErrorEvent} class for avaiable
+      # error event fields.
+      #
+      # @example Basic usage
+      #   # in app.rb
+      #   require "google/cloud/error_reporting"
+      #
+      #   begin
+      #     fail "boom"
+      #   rescue => exception
+      #     # Report exception using configuration parameters provided above
+      #     Google::Cloud::ErrorReporting.report exception
+      #   end
+      #
+      # @example The error event can be customized if needed
+      #   require "google/cloud/error_reporting"
+      #
+      #   begin
+      #     fail "boom"
+      #   rescue => exception
+      #     Google::Cloud::ErrorReporting.report exception do |error_event|
+      #       error_event.user = "johndoh@example.com"
+      #       error_event.http_status = "502"
+      #     end
+      #   end
+      #
+      # @param [Exception] exception The captured Ruby Exception object
+      # @param [String] service_name An identifier for running service.
+      #   Optional.
+      # @param [String] service_version A version identifier for running
+      #   service.
+      #
+      def self.report exception, service_name: nil, service_version: nil, &block
+        return if Google::Cloud.configure.use_error_reporting == false
+
+        unless @@default_client
+          project_id = configure.project_id ||
+                       Google::Cloud.configure.project_id
+          keyfile = configure.keyfile ||
+                    Google::Cloud.configure.keyfile
+
+          @@default_client = new project: project_id, keyfile: keyfile
+        end
+
+        service_name ||= configure.service_name
+        service_version ||= configure.service_version
+
+        @@default_client.report_exception exception,
+                                          service_name: service_name,
+                                          service_version: service_version,
+                                          &block
+      end
+    end
+  end
+end