Instrumente apps Ruby para o Error Reporting

Pode enviar relatórios de erros para o Error Reporting a partir de aplicações Ruby através da biblioteca Error Reporting para Ruby. Use a biblioteca Error Reporting para Ruby para criar grupos de erros nos seguintes casos:

• Um contentor de registos que contém as suas entradas de registo tem chaves de encriptação geridas pelo cliente (CMEK).
• O contentor de registos cumpre um dos seguintes requisitos:
  • O contentor de registos é armazenado no mesmo projeto onde as entradas de registo tiveram origem.
  • As entradas de registo foram encaminhadas para um projeto e, em seguida, esse projeto armazenou essas entradas de registo num contentor de registos que lhe pertence.
• Quer criar relatórios de eventos de erro personalizados.

O Error Reporting está integrado com alguns Google Cloud serviços, como o Cloud Functions e o App Engine, o Compute Engine e o Google Kubernetes Engine. O Error Reporting apresenta os erros registados no Cloud Logging por aplicações em execução nesses serviços. Para mais informações, aceda a Executar em Google Cloud nesta página.

Também pode enviar dados de erros para o Error Reporting através do Logging. Para obter informações sobre os requisitos de formatação de dados, leia o artigo Mensagens de erro de formatação no registo.

Antes de começar

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API .

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Error Reporting API .

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

1. Instale o Ruby 2.2+ ou superior.

Instale a biblioteca de cliente

A biblioteca Error Reporting para Ruby permite-lhe monitorizar e ver erros comunicados por aplicações Ruby executadas em praticamente qualquer lugar.

1. Adicione o Gem google-cloud-error_reporting ao seu Gemfile:

   gem "google-cloud-error_reporting"

2. Use o Bundler para instalar o gem:

   bundle install

Ativar a biblioteca

Se estiver a usar o Ruby on Rails, o Bundler carrega automaticamente a biblioteca na sua aplicação quando esta é iniciada.

Outras aplicações baseadas no Rack podem usar o middleware do Rack fornecido pela biblioteca:

require "google/cloud/error_reporting"

use Google::Cloud::ErrorReporting::Middleware

Para mais informações sobre a instalação, leia a documentação da biblioteca Error Reporting para Ruby. Também pode comunicar problemas através do relatório de erros.

Configure a biblioteca de cliente

Pode personalizar o comportamento da biblioteca Error Reporting para Ruby. Consulte a configuração da biblioteca para ver uma lista das opções de configuração possíveis.

Execute apps no Google Cloud

Para criar grupos de erros através de projects.events.report, a sua conta de serviço requer a função de escritor do Error Reporting (roles/errorreporting.writer).

Alguns Google Cloud serviços concedem automaticamente a função de autor de relatórios de erros (roles/errorreporting.writer) à conta de serviço adequada. No entanto, tem de conceder esta função à conta de serviço adequada para alguns serviços.

Cloud Run e funções do Cloud Run

A conta de serviço predefinida usada pelo Cloud Run tem as autorizações da função de escritor do Error Reporting (roles/errorreporting.writer).

A biblioteca Error Reporting para Ruby pode ser usada sem ter de fornecer explicitamente credenciais.

O Cloud Run está configurado para usar o Error Reporting automaticamente. As exceções de JavaScript não processadas aparecem no registo e são processadas pelo Error Reporting sem necessidade de usar a biblioteca Error Reporting para Ruby.

Usar a interface de configuração do Ruby on Rails

Para usar a biblioteca Error Reporting para Ruby com a framework Ruby on Rails, forneça os parâmetros através da interface de configuração do Ruby on Rails:

# 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

Também pode definir a configuração partilhada para todas as gems do Stackdriver através do seguinte:

# 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

Os relatórios de erros estão ativados por predefinição quando o Rails é executado no modo de produção. Para ativar os relatórios de erros no modo de desenvolvimento, adicione o seguinte:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

Usar a interface de configuração da instrumentação

Para usar a biblioteca Error Reporting para Ruby noutras aplicações baseadas em Rack, forneça os parâmetros através da interface de configuração:

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

Também pode definir a configuração partilhada para todas as gems do Google Cloud Observability usando o seguinte:

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

Ambiente flexível do App Engine

O App Engine concede automaticamente o papel de escritor do Error Reporting (roles/errorreporting.writer) à sua conta de serviço predefinida.

A biblioteca Error Reporting para Ruby pode ser usada sem ter de fornecer explicitamente credenciais.

Os relatórios de erros são ativados automaticamente para aplicações do ambiente flexível do App Engine. Não é necessária nenhuma configuração adicional.

Google Kubernetes Engine

Para usar o Error Reporting com o Google Kubernetes Engine, faça o seguinte:

1. Certifique-se de que a conta de serviço a ser usada pelo seu contentor tem a função Escritor de relatórios de erros (roles/errorreporting.writer).

   Pode usar a conta de serviço predefinida do Compute Engine ou uma conta de serviço personalizada.

   Para obter informações sobre a concessão de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

2. Crie o cluster e conceda ao cluster o cloud-platform âmbito de acesso.

   Por exemplo, o seguinte comando create especifica o cloud-platform âmbito de acesso e uma conta de serviço:

   gcloud container clusters create CLUSTER_NAME --service-account  SERVICE_ACCT_NAME --scopes=cloud-platform
   

Compute Engine

Para usar o Error Reporting com instâncias de VM do Compute Engine, faça o seguinte:

1. Certifique-se de que a conta de serviço a ser usada pela sua instância de VM tem a função de escritor de relatórios de erros (roles/errorreporting.writer).

   Pode usar a conta de serviço predefinida do Compute Engine ou uma conta de serviço personalizada.

   Para obter informações sobre a concessão de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

2. Na Google Cloud consola, aceda à página Instâncias de VM:

   Aceda a Instâncias de VM

   Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda seja Compute Engine.

3. Selecione a instância de VM que quer receber o cloud-platform âmbito de acesso.

4. Clique em Parar e, de seguida, em Editar.

5. Na secção Identidade e acesso à API, selecione uma conta de serviço que tenha a função de escritor do Error Reporting (roles/errorreporting.writer).

6. Na secção Âmbitos de acesso, selecione Permitir acesso total a todas as APIs Cloud e, de seguida, guarde as alterações.

7. Clique em Iniciar/Retomar.

Exemplo

Comunicação de erros em frameworks baseados em racks

A biblioteca Error Reporting para Ruby facilita a integração do Error Reporting em frameworks Web Ruby populares baseados em Rack, como o Ruby on Rails e o Sinatra. Quando a biblioteca está ativada, comunica automaticamente as exceções capturadas a partir da pilha do Rack da aplicação.

Comunicar erros manualmente

Pode comunicar manualmente um erro chamando o método report, como se vê no exemplo seguinte:
require "google/cloud/error_reporting"

begin
  raise "Something went wrong"
rescue StandardError => e
  Google::Cloud::ErrorReporting.report e
end

Execute apps num ambiente de programação local

Para usar a biblioteca Error Reporting para Ruby num ambiente de desenvolvimento local, como executar a biblioteca na sua própria estação de trabalho, tem de fornecer à biblioteca Error Reporting para Ruby as credenciais predefinidas da aplicação local. Para mais informações, consulte o artigo Autentique-se no Relatório de erros.

Para usar os Ruby exemplos nesta página num ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e, em seguida, configure as Credenciais predefinidas da aplicação com as suas credenciais de utilizador.

Instale a CLI Google Cloud.

Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro tem de iniciar sessão na CLI gcloud com a sua identidade federada.

If you're using a local shell, then create local authentication credentials for your user account:

gcloud auth application-default login

You don't need to do this if you're using Cloud Shell.

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.

Para mais informações, consulte Set up authentication for a local development environment.

O método projects.events.report também suporta chaves da API. Se quiser usar chaves de API para autenticação, não precisa de configurar um ficheiro de Credenciais padrão da aplicação local. Para mais informações, consulte Crie uma chave da API na Google Cloud documentação de autenticação.

Usar a interface de configuração do Ruby on Rails

Para usar a biblioteca Error Reporting para Ruby com a framework Ruby on Rails, forneça os parâmetros através da interface de configuração do Ruby on Rails:

# 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

Também pode definir a configuração partilhada para todas as gems do Stackdriver através do seguinte:

# 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

Os relatórios de erros estão ativados por predefinição quando o Rails é executado no modo de produção. Para ativar os relatórios de erros no modo de desenvolvimento, adicione o seguinte:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_error_reporting = true
end

Usar a interface de configuração da instrumentação

Para usar a biblioteca Error Reporting para Ruby noutras aplicações baseadas em Rack, forneça os parâmetros através da interface de configuração:

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

Também pode definir a configuração partilhada para todas as gems do Google Cloud Observability usando o seguinte:

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

Visualizar relatórios de erros

Na Google Cloud consola, aceda à página Error Reporting:

Aceda a Error Reporting

Também pode encontrar esta página através da barra de pesquisa.

Para mais informações, consulte o artigo Ver erros.