Instrumente apps Java para o Error Reporting

Pode enviar relatórios de erros para o Error Reporting a partir de aplicações Java através do pacote Error Reporting para Java. Use o pacote Error Reporting para Java 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

Instale a biblioteca de cliente

O pacote Error Reporting para Java permite-lhe monitorizar e ver erros comunicados por aplicações Java executadas em praticamente qualquer lugar.

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

Configure a biblioteca de cliente

Pode personalizar o comportamento do pacote Error Reporting para Java. Consulte a documentação de referência da API Java.

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

O pacote Error Reporting para Java pode ser usado 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 o pacote Error Reporting para Java.

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.

O pacote Error Reporting para Java pode ser usado 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.
@WebServlet(name = "Error reporting", value = "/error")
public class ErrorReportingExample extends HttpServlet {

  private Logger logger = Logger.getLogger(ErrorReportingExample.class.getName());

  @Override
  public void doGet(HttpServletRequest req, HttpServletResponse resp)
      throws IOException, ServletException {

    // errors logged to stderr / Cloud logging with exceptions are automatically reported.
    logger.log(Level.SEVERE, "exception using log framework", new IllegalArgumentException());

    // use the error-reporting client library only if you require logging custom error events.
    logCustomErrorEvent();

    // runtime exceptions are also automatically reported.
    throw new RuntimeException("this is a runtime exception");
  }

  private void logCustomErrorEvent() {
    try (ReportErrorsServiceClient reportErrorsServiceClient = ReportErrorsServiceClient.create()) {
      // Custom error events require an error reporting location as well.
      ErrorContext errorContext =
          ErrorContext.newBuilder()
              .setReportLocation(
                  SourceLocation.newBuilder()
                      .setFilePath("Test.java")
                      .setLineNumber(10)
                      .setFunctionName("myMethod")
                      .build())
              .build();
      // Report a custom error event
      ReportedErrorEvent customErrorEvent =
          ReportedErrorEvent.getDefaultInstance()
              .toBuilder()
              .setMessage("custom error event")
              .setContext(errorContext)
              .build();

      // default project id
      ProjectName projectName = ProjectName.of(ServiceOptions.getDefaultProjectId());
      reportErrorsServiceClient.reportErrorEvent(projectName, customErrorEvent);
    } catch (Exception e) {
      logger.log(Level.SEVERE, "Exception encountered logging custom event", e);
    }
  }
}

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

As exceções registadas através do Cloud Logging Logback Appender ou do java.util.logging Handler são comunicadas automaticamente à consola do Error Reporting.

O exemplo seguinte demonstra a utilização da biblioteca cliente Java para comunicar um evento de erro personalizado:

import com.google.cloud.ServiceOptions;
import com.google.devtools.clouderrorreporting.v1beta1.ProjectName;
import com.google.devtools.clouderrorreporting.v1beta1.ReportErrorsServiceClient;
import com.google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent;
import java.io.IOException;
import java.io.PrintWriter;
import java.io.StringWriter;

/**
 * Snippet demonstrates using the Error Reporting API to report an exception.
 * <p>
 * When the workload runs on App Engine, GKE, Cloud Functions or another managed environment,
 * printing the exception's stack trace to stderr will automatically report the error
 * to Error Reporting.
 */
public class QuickStart {

  static String projectId;

  public static void main(String[] args) throws Exception {
    // Set your Google Cloud Platform project ID via environment or explicitly
    projectId = ServiceOptions.getDefaultProjectId();
    if (args.length > 0) {
      projectId = args[0];
    } else {
      String value = System.getenv("GOOGLE_CLOUD_PROJECT");
      if (value != null && value.isEmpty()) {
        projectId = value;
      }
    }

    try {
      throw new Exception("Something went wrong");
    } catch (Exception ex) {
      reportError(ex);
    }
  }

  /**
   * Sends formatted error report to Google Cloud including the error context.
   *
   * @param ex Exception containing the error and the context.
   * @throws IOException if fails to communicate with Google Cloud
   */
  private static void reportError(Exception ex) throws IOException {
    try (ReportErrorsServiceClient serviceClient = ReportErrorsServiceClient.create()) {
      StringWriter sw = new StringWriter();
      PrintWriter pw = new PrintWriter(sw);
      ex.printStackTrace(pw);

      ReportedErrorEvent errorEvent = ReportedErrorEvent.getDefaultInstance()
          .toBuilder()
          .setMessage(sw.toString())
          .build();
      // If you need to report an error asynchronously, use reportErrorEventCallable()
      // method
      serviceClient.reportErrorEvent(ProjectName.of(projectId), errorEvent);
    }
  }
}

Consulte a documentação de referência da API Java sobre como obter e gerir estatísticas de erros, bem como dados para eventos individuais.

Execute apps num ambiente de programação local

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

Para usar os Java 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.

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.