Module: Google::Cloud::ErrorReporting

Defined in:
lib/google/cloud/error_reporting.rb,
lib/google/cloud/error_reporting/rails.rb,
lib/google/cloud/error_reporting/project.rb,
lib/google/cloud/error_reporting/service.rb,
lib/google/cloud/error_reporting/version.rb,
lib/google/cloud/error_reporting/middleware.rb,
lib/google/cloud/error_reporting/credentials.rb,
lib/google/cloud/error_reporting/error_event.rb,
lib/google/cloud/error_reporting/async_error_reporter.rb,
lib/google/cloud/error_reporting/v1beta1/error_group_service_client.rb,
lib/google/cloud/error_reporting/v1beta1/error_stats_service_client.rb,
lib/google/cloud/error_reporting/v1beta1/report_errors_service_client.rb

Overview

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 from your application.

For general information about Stackdriver Error Reporting, read Stackdriver Error Reporting Documentation.

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.

How to report errors

You can easily report exceptions from your applications to Stackdriver Error Reporting service:

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 for more examples.

Defined Under Namespace

Modules: V1beta1 Classes: ErrorEvent, Middleware, Project, Railtie

Constant Summary collapse

VERSION = 
"0.26.1".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.error_reporting| ... } ⇒ Stackdriver::Core::Configuration

Configure the default Project client, allows the report public method to reuse these configured parameters.

See the Configuration Guide for full configuration parameters.

Examples:

# 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

Yields:

Returns:

  • (Stackdriver::Core::Configuration) —

    The configuration object the Google::Cloud::ErrorReporting module uses.



166
167
168
169
170
 
# File 'lib/google/cloud/error_reporting.rb', line 166

def self.configure
  yield Google::Cloud.configure.error_reporting if block_given?

  Google::Cloud.configure.error_reporting
end

.new(project: nil, keyfile: nil, scope: nil, timeout: nil, client_config: nil) ⇒ Google::Cloud::ErrorReporting::Project

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.

Examples:

require "google/cloud/error_reporting"

error_reporting = Google::Cloud::ErrorReporting.new
# ...

Parameters:

  • project (String) —

    Project identifier for the Stackdriver Error Reporting service.

  • keyfile (String, Hash) —

    Keyfile downloaded from Google Cloud. If file path the file must be readable.

  • scope (String, Array<String>) —

    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.

    The default scope is:

    • https://www.googleapis.com/auth/cloud-platform
  • timeout (Integer) —

    Default timeout to use in requests. Optional.

  • client_config (Hash) —

    A hash of values to override the default behavior of the API client. Optional.

Returns:



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/google/cloud/error_reporting.rb', line 119

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

.report(exception, service_name: nil, service_version: nil) {|error_event| ... } ⇒ Object

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 ErrorEvent class for avaiable error event fields.

Examples:

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

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

Parameters:

  • exception (Exception) —

    The captured Ruby Exception object

  • service_name (String) —

    An identifier for running service. Optional.

  • service_version (String) —

    A version identifier for running service.

Yields:

  • (error_event) 


217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/google/cloud/error_reporting.rb', line 217

def self.report exception, service_name: nil, service_version: nil
  return if Google::Cloud.configure.use_error_reporting == false

  service_name ||= configure.service_name ||
                   Project.default_service_name
  service_version ||= configure.service_version ||
                      Project.default_service_version

  error_event = ErrorEvent.from_exception(exception).tap do |event|
    event.service_name = service_name
    event.service_version = service_version
  end

  yield error_event if block_given?

  default_client.report error_event
end