The [Error Reporting library for Ruby](https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-error_reporting) lets you send error events directly
from your Ruby applications to Error Reporting so that
you can diagnose and monitor runtime crashes. Instrumenting your application
with the library lets you report custom error events and capture errors even
when your log buckets use [customer-managed encryption keys (CMEK)](https://docs.cloud.google.com/kms/docs/cmek.md.txt).
For applications running on integrated Google Cloud services---including
[Cloud Run functions](https://docs.cloud.google.com/error-reporting/docs/setup/ruby.md.txt#cloud_functions),
[App Engine](https://docs.cloud.google.com/appengine/docs.md.txt), [Compute Engine](https://docs.cloud.google.com/compute/docs.md.txt), and
[Google Kubernetes Engine](https://docs.cloud.google.com/kubernetes-engine/docs.md.txt)---Error Reporting can also infer error
events automatically from Cloud Logging without the Error Reporting library for Ruby.
For Error Reporting to infer error events from logs, your
log entries must follow the
[error formatting requirements](https://docs.cloud.google.com/error-reporting/docs/formatting-error-messages.md.txt)
and be stored in a non-CMEK log bucket owned by the originating project or by
the destination project to which the logs were routed.
## Before you begin
1. Install [Ruby 2.2+](https://www.ruby-lang.org/en/downloads/) or greater.
## Install the client library
The Error Reporting library for Ruby lets you monitor and view error events reported by
Ruby applications running nearly anywhere.
1. Add the `google-cloud-error_reporting` gem to your Gemfile:
```
gem "google-cloud-error_reporting"
```
2. Use [Bundler](http://bundler.io/) to install the gem:
```
bundle install
```
### Enabling the library
If you're using Ruby on Rails, Bundler automatically loads the library into
your application when it starts.
Other Rack-based applications can use the Rack Middleware provided by the
library:
```ruby
require "google/cloud/error_reporting"
use Google::Cloud::ErrorReporting::Middleware
```
For more information on installation, read the
[documentation](https://github.com/GoogleCloudPlatform/google-cloud-ruby/tree/master/google-cloud-error_reporting) for the
Error Reporting library for Ruby. You can also report issues using the
[issue tracker](https://github.com/GoogleCloudPlatform/google-cloud-ruby/issues).
### Configure the client library
You can customize the behavior of the Error Reporting library for Ruby. See
[the library's configuration](https://github.com/GoogleCloudPlatform/google-cloud-ruby/blob/master/stackdriver/INSTRUMENTATION_CONFIGURATION.md) for a list of
possible configuration options.
## Run apps on Google Cloud
To create error groups by using
[`projects.events.report`](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt), your service account requires the
[Error Reporting Writer role](https://docs.cloud.google.com/error-reporting/docs/iam.md.txt#errorreporting.writer) (`roles/errorreporting.writer`).
Some Google Cloud services automatically grant the
Error Reporting Writer role (`roles/errorreporting.writer`) to the appropriate
service account. However, you must grant this role to the appropriate service
account for some services.
### Cloud Run and Cloud Run functions
The default service account used by [Cloud Run](https://docs.cloud.google.com/run/docs.md.txt) has the
permissions of [Error Reporting Writer role](https://docs.cloud.google.com/error-reporting/docs/iam.md.txt#errorreporting.writer) (`roles/errorreporting.writer`).
The Error Reporting library for Ruby can be used without needing to explicitly provide
credentials.
Cloud Run is configured to use Error Reporting
automatically. Unhandled
JavaScript exceptions will appear in Logging and be processed by
Error Reporting without needing to use the
Error Reporting library for Ruby.
> [!NOTE]
> **Note:** Error Reporting automatically creates an error event when a log entry contains a stack trace and the severity level of the log entry isn't set or is set to at least `ERROR`.
### Using Ruby on Rails configuration interface
To use the Error Reporting library for Ruby with the Ruby on Rails framework, provide the
parameters through the Ruby on Rails configuration interface:
```ruby
# Add this to config/environments/*.rb
Rails.application.configure do |config|
# Stackdriver Error Reporting specific parameters
config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
config.google_cloud.error_reporting.keyfile = "/path/to/service-account.json"
end
```
You can also set shared configuration for all Stackdriver gems using the
following:
```ruby
# Add this to config/environments/*.rb
Rails.application.configure do |config|
# Stackdriver Shared parameters
config.google_cloud.project_id = "YOUR-PROJECT-ID"
config.google_cloud.keyfile = "/path/to/service-account.json"
end
```
Error Reporting is enabled by default when Rails is running in
production mode. To enable Error Reporting in development
mode, add the following:
```ruby
# Add this to config/environments/development.rb
Rails.application.configure do |config|
config.google_cloud.use_error_reporting = true
end
```
### Using instrumentation configuration interface
To use the Error Reporting library for Ruby in other Rack-based applications, provide the
parameters through the configuration interface:
```ruby
require "google/cloud/error_reporting"
Google::Cloud.configure do |config|
# Stackdriver Error Reporting specific parameters
config.error_reporting.project_id = "YOUR-PROJECT-ID"
config.error_reporting.keyfile = "/path/to/service-account.json"
end
```
You can also set shared configuration for all Google Cloud Observability gems
using the following:
```ruby
require "stackdriver"
Google::Cloud.configure do |config|
# Stackdriver Shared parameters
config.project_id = "YOUR-PROJECT-ID"
config.keyfile = "/path/to/service-account.json"
end
```
### App Engine flexible environment
[App Engine](https://docs.cloud.google.com/appengine/docs.md.txt) grants the
[Error Reporting Writer role](https://docs.cloud.google.com/error-reporting/docs/iam.md.txt#errorreporting.writer) (`roles/errorreporting.writer`)
to your default service account automatically.
The Error Reporting library for Ruby can be used without needing to explicitly provide
credentials.
Error Reporting is automatically enabled for App Engine flexible environment applications. No additional setup is required.
> [!NOTE]
> **Note:** Error log entries written to `stderr` are processed automatically by Error Reporting, without needing to use the Error Reporting library for Ruby directly.
### Google Kubernetes Engine
To use Error Reporting with Google Kubernetes Engine,
do the following:
1. Ensure that the service account to be used by your container has been
granted the
[Error Reporting Writer role](https://docs.cloud.google.com/error-reporting/docs/iam.md.txt#errorreporting.writer) (`roles/errorreporting.writer`).
You can use either the [Compute Engine default service account](https://docs.cloud.google.com/compute/docs/access/service-accounts.md.txt#default_service_account)
or a custom service account.
For information about granting roles, see
[Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).
2. Create your cluster and grant the cluster the
`cloud-platform` [access scope](https://docs.cloud.google.com/compute/docs/access/service-accounts.md.txt#accesscopesiam).
For example, the following create command specifies the `cloud-platform`
access scope and a service account:
```
gcloud container clusters create CLUSTER_NAME --service-account SERVICE_ACCT_NAME --scopes=cloud-platform
```
> [!NOTE]
> **Note:** After you create a cluster, you can't change its service account.
### Compute Engine
To use Error Reporting with Compute Engine VM instances,
do the following:
1. Ensure that the service account to be used by your VM instance has been
granted the
[Error Reporting Writer role](https://docs.cloud.google.com/error-reporting/docs/iam.md.txt#errorreporting.writer) (`roles/errorreporting.writer`).
You can use either the [Compute Engine default service account](https://docs.cloud.google.com/compute/docs/access/service-accounts.md.txt#default_service_account)
or a custom service account.
For information about granting roles, see
[Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).
2. In the Google Cloud console, go to the **VM instances** page:
[Go to **VM instances**](https://console.cloud.google.com/compute/instances)
If you use the search bar to find this page, then select the result whose subheading is
**Compute Engine**.
3. Select the VM instance that you want to receive the
`cloud-platform` [access scope](https://docs.cloud.google.com/compute/docs/access/service-accounts.md.txt#accesscopesiam).
4. Click **Stop** , and then click **Edit**.
5. In the **Identity and API access** section, select a service account that
has the Error Reporting Writer role (`roles/errorreporting.writer`).
6. In the **Access scopes** section,
select **Allow full access to all Cloud APIs**, and then save your changes.
7. Click **Start/Resume**.
## Example
### Reporting errors in Rack-based frameworks
The Error Reporting library for Ruby makes it easy to integrate
Error Reporting
into popular Rack-based Ruby web frameworks such as Ruby on Rails and Sinatra.
When the library is enabled, it automatically reports exceptions captured from
the application's Rack stack.
### Reporting errors manually
You can manually report an error by calling the `report` method, as seen in the following example:
```ruby
require "google/cloud/error_reporting"
begin
raise "Something went wrong"
rescue StandardError => e
Google::Cloud::ErrorReporting.report e
end
```
## Run apps in a local development environment
To use the Error Reporting library for Ruby in a local development environment,
such as running the library on your own workstation, you must provide
your Error Reporting library for Ruby with the local application default credentials.
For more information, see [Authenticate to Error Reporting](https://docs.cloud.google.com/error-reporting/docs/reference/authentication.md.txt#client-libs).
To use the Ruby samples on this page in a local development environment, install and
initialize the gcloud CLI, and then set up Application Default Credentials with
your user credentials.
1.
[Install](https://docs.cloud.google.com/sdk/docs/install) the Google Cloud CLI.
2. If you're using an external identity provider (IdP), you must first
[sign in to the gcloud CLI with your federated identity](https://docs.cloud.google.com/iam/docs/workforce-log-in-gcloud.md.txt).
3.
If you're using a local shell, then create local authentication credentials for your user
account:
```bash
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.
> [!NOTE]
>
> **Note:** If the gcloud CLI prints a warning that your account
> doesn't have the `serviceusage.services.use` permission, then some
> gcloud CLI commands and client libraries might not work. Ask an
> administrator to grant you the Service Usage Consumer IAM role
> (`roles/serviceusage.serviceUsageConsumer`), then run the following command:
>
> ```bash
> gcloud auth application-default set-quota-project PROJECT_ID
> ```
If an authentication error is returned, and you are using an external identity provider
(IdP), confirm that you have
[signed in to the gcloud CLI with your federated identity](https://docs.cloud.google.com/iam/docs/workforce-log-in-gcloud.md.txt).
For more information, see
[Set up authentication for a local development environment](https://docs.cloud.google.com/error-reporting/docs/reference/authentication.md.txt#local-development).
The [`projects.events.report` method](https://docs.cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report.md.txt) also
supports API keys.
If you want to use API keys for authentication, you do not need
to set up a local Application Default Credentials file.
For more information, see
[Create an API key](https://docs.cloud.google.com/docs/authentication/api-keys.md.txt#create)
in the Google Cloud authentication documentation.
### Using Ruby on Rails configuration interface
To use the Error Reporting library for Ruby with the Ruby on Rails framework, provide the
parameters through the Ruby on Rails configuration interface:
```ruby
# Add this to config/environments/*.rb
Rails.application.configure do |config|
# Stackdriver Error Reporting specific parameters
config.google_cloud.error_reporting.project_id = "YOUR-PROJECT-ID"
config.google_cloud.error_reporting.keyfile = "/path/to/service-account.json"
end
```
You can also set shared configuration for all Stackdriver gems using the
following:
```ruby
# Add this to config/environments/*.rb
Rails.application.configure do |config|
# Stackdriver Shared parameters
config.google_cloud.project_id = "YOUR-PROJECT-ID"
config.google_cloud.keyfile = "/path/to/service-account.json"
end
```
Error Reporting is enabled by default when Rails is running in
production mode. To enable Error Reporting in development
mode, add the following:
```ruby
# Add this to config/environments/development.rb
Rails.application.configure do |config|
config.google_cloud.use_error_reporting = true
end
```
### Using instrumentation configuration interface
To use the Error Reporting library for Ruby in other Rack-based applications, provide the
parameters through the configuration interface:
```ruby
require "google/cloud/error_reporting"
Google::Cloud.configure do |config|
# Stackdriver Error Reporting specific parameters
config.error_reporting.project_id = "YOUR-PROJECT-ID"
config.error_reporting.keyfile = "/path/to/service-account.json"
end
```
You can also set shared configuration for all Google Cloud Observability gems
using the following:
```ruby
require "stackdriver"
Google::Cloud.configure do |config|
# Stackdriver Shared parameters
config.project_id = "YOUR-PROJECT-ID"
config.keyfile = "/path/to/service-account.json"
end
```
## View error groups
In the Google Cloud console, go to the **Error Reporting** page:
[Go to **Error Reporting**](https://console.cloud.google.com/errors)
You can also find this page by using the search bar.
For more information, see
[View and filter error groups](https://docs.cloud.google.com/error-reporting/docs/viewing-errors.md.txt).