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/doc/overview.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

Ruby Client for Stackdriver Error Reporting API (Beta)

Stackdriver Error Reporting API: Stackdriver Error Reporting groups and counts similar errors from cloud services. The Stackdriver Error Reporting API provides a way to report new errors and read access to error groups and their associated errors.

Quick Start

In order to use this library, you first need to go through the following steps:

  1. Select or create a Cloud Platform project.
  2. Enable the Stackdriver Error Reporting API.
  3. Setup Authentication.

Installation

$ gem install google-cloud-error_reporting

Preview

ReportErrorsServiceClient

require "google/cloud/error_reporting"

report_errors_service_client = Google::Cloud::ErrorReporting::ReportErrors.new
formatted_project_name = Google::Cloud::ErrorReporting::V1beta1::ReportErrorsServiceClient.project_path(project_id)
message = "[MESSAGE]"
service = "[SERVICE]"
service_context = { service: service }
file_path = "path/to/file.lang"
line_number = 42
function_name = "meaningOfLife"
report_location = {
  file_path: file_path,
  line_number: line_number,
  function_name: function_name
}
context = { report_location: report_location }
event = {
  message: message,
  service_context: service_context,
  context: context
}
response = report_errors_service_client.report_error_event(formatted_project_name, event)

Next Steps

Defined Under Namespace

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

Constant Summary collapse

VERSION = 
"0.30.1".freeze

Class Method Summary collapse

Class Method Details

.configure {|Google::Cloud.configure.error_reporting| ... } ⇒ Google::Cloud::Config

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

The following Stackdriver ErrorReporting configuration parameters are supported:

  • project_id - (String) Google Cloud Platform project identifier for the Stackdriver Error Reporting service you are connecting to. (The parameter project is considered deprecated, but may also be used.)
  • credentials - (String, Hash, Google::Auth::Credentials) The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials) (The parameter keyfile is considered deprecated, but may also be used.)
  • scope - (String, Array) The OAuth 2.0 scopes controlling the set of resources and operations that the connection can access.
  • timeout - (Integer) Default timeout to use in requests.
  • client_config - (Hash) A hash of values to override the default behavior of the API client.
  • service_name - (String) Name for the application.
  • service_version - (String) Version identifier for the application.
  • ignore_classes - (Array) Array of exception types that should not be reported.

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"
  config.credentials = "/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:

  • (Google::Cloud::Config) —

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



229
230
231
232
233
 
# File 'lib/google/cloud/error_reporting.rb', line 229

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

  Google::Cloud.configure.error_reporting
end

.new(project_id: nil, credentials: nil, scope: nil, timeout: nil, client_config: nil, project: nil, keyfile: 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_id (String) —

    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.

  • credentials (String, Hash, Google::Auth::Credentials) —

    The path to the keyfile as a String, the contents of the keyfile as a Hash, or a Google::Auth::Credentials object. (See Credentials)

  • 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.

  • project (String) —

    Alias for the project_id argument. Deprecated.

  • keyfile (String) —

    Alias for the credentials argument. Deprecated.

Returns:

Raises:

  • (ArgumentError) 


154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
 
# File 'lib/google/cloud/error_reporting.rb', line 154

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
  raise ArgumentError, "project_id is missing" if project_id.empty?

  scope ||= configure.scope
  timeout ||= configure.timeout
  client_config ||= configure.client_config

  credentials ||= (keyfile || default_credentials(scope: scope))
  unless credentials.is_a? Google::Auth::Credentials
    credentials = ErrorReporting::Credentials.new credentials,
                                                  scope: scope
  end

  ErrorReporting::Project.new(
    ErrorReporting::Service.new(
      project_id, 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) 


280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
 
# File 'lib/google/cloud/error_reporting.rb', line 280

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

  service_name ||= Project.default_service_name
  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