Como configurar o Error Reporting para Node.js

É possível enviar relatórios de erros para o Error Reporting a partir de aplicativos Node.js usando a biblioteca Error Reporting para Node.js (em inglês).

O Error Reporting é integrado a alguns serviços do Google Cloud, como Cloud Functions, App Engine, Compute Engine e Google Kubernetes Engine. Essa ferramenta exibe os erros registrados no Cloud Logging por aplicativos em execução nesses serviços. Para mais informações, consulte a seção Como executar no Google Cloud Platform nesta página.

Também é possível enviar dados de erros para o Error Reporting usando o Logging. Para mais informações sobre os requisitos de formatação de dados, leia Como formatar mensagens de erro no Logging (em inglês).

Antes de começar

  1. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
  2. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  3. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  4. Ative a Error Reporting API .

    Ative a API

  5. No Console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto do Google Cloud.

    Acessar o seletor de projetos

  6. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como confirmar se o faturamento está ativado para o projeto.

  7. Ative a Error Reporting API .

    Ative a API

  8. Prepare o ambiente para o desenvolvimento do Node.js.

    Acessar o guia de configuração do Node.js

Instalar a biblioteca de cliente

Com a biblioteca do Error Reporting para Node.js, você consegue monitorar e visualizar os erros relatados por aplicativos Node.js executados em praticamente qualquer lugar.

  1. Use npm para instalar o pacote:

    npm install --save @google-cloud/error-reporting
  2. Importe a biblioteca e instancie um cliente para começar a relatar erros:

    // Imports the Google Cloud client library
    const {ErrorReporting} = require('@google-cloud/error-reporting');
    
    // Instantiates a client
    const errors = new ErrorReporting();
    
    // Reports a simple error
    errors.report('Something broke!');

Para mais informações sobre a instalação, leia a documentação da biblioteca do Error Reporting para Node.js (em inglês). Além disso, use o rastreador de problemas (em inglês) para informá-los.

Como configurar a biblioteca de cliente

É possível personalizar o comportamento da biblioteca do Error Reporting para Node.js. Consulte a configuração da biblioteca para ver uma lista das possíveis opções de configuração. Essas opções podem ser transmitidas no objeto options para o construtor da biblioteca.

Como relatar erros

É possível relatar um erro, manualmente, chamando o método report, conforme visto no exemplo a seguir:

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

// Use the error message builder to customize all fields ...
const errorEvent = errors.event();

// Add error information
errorEvent.setMessage('My error message');
errorEvent.setUser('root@nexus');

// Report the error event
errors.report(errorEvent, () => {
  console.log('Done reporting error event!');
});

// Report an Error object
errors.report(new Error('My error message'), () => {
  console.log('Done reporting Error object!');
});

// Report an error by provided just a string
errors.report('My error message', () => {
  console.log('Done reporting error string!');
});

Como relatar erros com o Express.js

A biblioteca do Error Reporting para Node.js pode integrar o Error Reporting aos frameworks da Web do Node.js mais conhecidos, como o Express.js:

const express = require('express');

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting();

const app = express();

app.get('/error', (req, res, next) => {
  res.send('Something broke!');
  next(new Error('Custom error message'));
});

app.get('/exception', () => {
  JSON.parse('{"malformedJson": true');
});

// Note that express error handling middleware should be attached after all
// the other routes and use() calls. See the Express.js docs.
app.use(errors.express);

const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

Outras integrações

Para mais informações sobre integrações entre a biblioteca do Error Reporting para Node.js e outros frameworks da Web do Node.js, consulte o repositório da biblioteca no GitHub (em inglês).

Como executar no Google Cloud

O uso da biblioteca do Error Reporting para Node.js exige o papel Gravador do Error Reporting do Gerenciamento de identidade e acesso. Por padrão, a maioria das plataformas de computação do Google Cloud concede esse papel.

É possível configurar o Error Reporting para Node.js nos seguintes ambientes do Google Cloud.

Ambiente flexível do App Engine

O App Engine concede o papel Gravador do Error Reporting (em inglês) por padrão.

A biblioteca do Error Reporting para Node.js pode ser usada sem a necessidade de fornecer credenciais explicitamente.

O Error Reporting é ativado automaticamente para aplicativos do ambiente flexível do App Engine. Nenhuma outra configuração é necessária.

Google Kubernetes Engine

No GKE, você precisa adicionar o escopo de acesso cloud-platform ao criar o cluster, como mostra este exemplo de comando:

gcloud container clusters create example-cluster-name --scopes https://www.googleapis.com/auth/cloud-platform

Compute Engine

Ao usar instâncias de VM do Compute Engine, adicione o escopo de acesso cloud-platform a cada instância. Ao criar uma nova instância por meio do Console do Google Cloud, é possível adicionar o escopo na seção Identidade e acesso à API do painel Criar instância. Use a conta de serviço padrão do Compute Engine ou outra de sua escolha e selecione Permitir acesso completo a todas as APIs do Cloud na seção Identidade e acesso à API. Seja qual for a conta de serviço selecionada, verifique se ela recebeu o papel Gravador do Error Reporting (em inglês) na seção IAM e administrador do Console do Cloud.

Cloud Functions

O Cloud Functions concede o papel Gravador do Error Reporting por padrão.

A biblioteca do Error Reporting para Node.js pode ser usada sem a necessidade de fornecer credenciais explicitamente.

O Cloud Functions está configurado para usar o Error Reporting automaticamente. As exceções de JavaScript não processadas serão exibidas no Logging e processadas pelo Error Reporting sem a necessidade de usar a biblioteca dessa ferramenta para Node.js.

Execução local e em outro lugar

Para usar a biblioteca do Error Reporting para Node.js fora do Google Cloud, incluindo a execução da biblioteca na sua própria estação de trabalho, nos computadores do seu data center ou nas instâncias de VM de outro provedor de nuvem, forneça as credenciais da conta de serviço e o ID do projeto do Google Cloud diretamente para a biblioteca do Error Reporting para Node.js.

É possível criar e receber credenciais da conta de serviço manualmente. Ao especificar o campo Papel, use o papel de gravador do Error Reporting. Para mais informações sobre papéis de gerenciamento de identidade e acesso, consulte o guia de controle de acesso.

Exemplo:

// Imports the Google Cloud client library
const {ErrorReporting} = require('@google-cloud/error-reporting');

// Instantiates a client
const errors = new ErrorReporting({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

// Reports a simple error
errors.report('Something broke!');

Como visualizar relatórios de erros

Após a implantação, é possível visualizar os relatórios de erros no painel do Error Reporting no Console do Cloud.

Acessar o painel do Error Reporting

Para mais informações, consulte Como visualizar erros.