Como fazer configurações no Compute Engine

Com o Error Reporting, é possível agregar falhas e diagnosticar exceções de tempo de execução dos aplicativos do Compute Engine. É possível enviar dados de erros transmitindo registros para o Cloud Logging ou chamando a API Error Reporting diretamente. Se você usa o Logging, as entradas de registro precisam seguir os requisitos de formatação.

Usar o Logging para relatar erros

Atenção:a partir de 28 de setembro de 2026, o agente legado do Logging não terá mais suporte. A manutenção padrão e as correções de bugs não são mais fornecidas. Recomendamos migrar para uma das alternativas compatíveis. Para mais informações sobre essa descontinuação, consulte Fim do suporte aos agentes legados do Monitoring e Logging.

Para conectar seus aplicativos do Compute Engine ao Error Reporting, envie exceções ou outros erros ao Logging usando um dos seguintes agentes:

• Agente de operações
• Agente legado do Logging

Agente de operações

Para configurar o Error Reporting para usar o Agente de operações, siga estas etapas:

1. Instale o Agente de operações de acordo com seu ambiente. Para instruções, consulte Como instalar o Agente de operações.

2. Configure o Agente de operações para coletar os registros do aplicativo e formatá-los corretamente.

   • Para aplicativos de terceiros compatíveis:o Agente de operações fornece receptores de geração de registros pré-configurados que capturam e analisam automaticamente entradas de registro em formatos estruturados reconhecidos pelo Error Reporting. Para informações sobre os aplicativos de terceiros compatíveis, consulte Monitoramento de aplicativos de terceiros.

   • Para aplicativos personalizados:configure um receptor de geração de registros para especificar os locais dos arquivos de registro e pareie com um dos seguintes processadores:

     • Use um processador parse_multiline se o app gravar rastreamentos de pilha de texto simples em várias linhas.
     • Use um processador parse_json se o app gravar registros como strings JSON.

     Para instruções detalhadas, consulte Configurar o Agente de operações.

3. Se o aplicativo não gerar rastreamentos de pilha padrão, modifique-o para registrar exceções e rastreamentos de pilha no Cloud Logging.

   É preciso incluir todas as informações de um único erro ou exceção na mesma entrada de registro, incluindo todos os frames de qualquer stack trace. Se todas as informações não estiverem juntas, o Error Reporting poderá não detectar o erro. É possível usar o formato JSON estruturado nos seus payloads de entrada de registro para incluir diferentes tipos de informações de cada erro.

Agente legado do Logging

Para configurar o Error Reporting para usar o agente do Logging legado, siga estas etapas:

1. Instale o agente do Logging google-fluentd no estado em que se encontra, conforme apropriado para seu ambiente. Para instruções, consulte Como instalar o agente do Logging.

2. Modifique o aplicativo para que ele registre exceções e respectivos rastreamentos de pilha no Logging.

   Inclua todas as informações de um único erro ou exceção na mesma entrada de registro, incluindo todos os frames de qualquer stack trace. Se todas as informações não estiverem juntas, o Error Reporting poderá não detectar o erro. É possível usar o formato JSON estruturado nos seus payloads de entrada de registro para incluir diferentes tipos de informações de cada erro.

Java

Adicione a instrução a seguir ao seu arquivo pom.xml:

<dependency>
  <groupId>org.fluentd</groupId>
  <artifactId>fluent-logger</artifactId>
  <version>0.3.4</version>
</dependency>

Depois, use o código como o demonstrado a seguir para enviar os dados da exceção:

public class ExceptionUtil {
  private static FluentLogger ERRORS = FluentLogger.getLogger("myapp");

  public static void main(String[] args) {
    try {
      throw new Exception("Generic exception for testing Stackdriver");
    } catch (Exception e) {
      report(e);
    }
  }

  public static void report(Throwable ex) {
    StringWriter exceptionWriter = new StringWriter();
    ex.printStackTrace(new PrintWriter(exceptionWriter));
    Map<String, Object> data = new HashMap<>();
    data.put("message", exceptionWriter.toString());
    Map<String, String> serviceContextData = new HashMap<>();
    serviceContextData.put("service", "myapp");
    data.put("serviceContext", serviceContextData);
    // ... add more metadata
    ERRORS.log("errors", data);
  }
}

Python

Primeiro, instale a biblioteca fluent-logger-python (em inglês):

sudo pip install fluent-logger

Depois, use o código como o demonstrado a seguir para enviar os dados da exceção:

import traceback

import fluent.event
import fluent.sender


def simulate_error():
    fluent.sender.setup("myapp", host="localhost", port=24224)

    def report(ex):
        data = {}
        data["message"] = "{0}".format(ex)
        data["serviceContext"] = {"service": "myapp"}
        # ... add more metadata
        fluent.event.Event("errors", data)

    # report exception data using:
    try:
        # simulate calling a method that's not defined
        raise NameError
    except Exception:
        report(traceback.format_exc())

Node.js

Primeiro, instale a biblioteca fluent-logger-node (em inglês):

npm install fluent-logger

Depois, use o código como o demonstrado a seguir para enviar os dados da exceção:

const structuredLogger = require('fluent-logger').createFluentSender('myapp', {
  host: 'localhost',
  port: 24224,
  timeout: 3.0,
});

const report = (err, req) => {
  const payload = {
    serviceContext: {
      service: 'myapp',
    },
    message: err.stack,
    context: {
      httpRequest: {
        url: req.originalUrl,
        method: req.method,
        referrer: req.header('Referer'),
        userAgent: req.header('User-Agent'),
        remoteIp: req.ip,
        responseStatusCode: 500,
      },
    },
  };
  structuredLogger.emit('errors', payload);
};

// Handle errors (the following uses the Express framework)
// eslint-disable-next-line no-unused-vars
app.use((err, req, res, next) => {
  report(err, req);
  res.status(500).send(err.response || 'Something broke!');
});

Go

Primeiro, instale o pacote fluent-logger-golang (em inglês):

go get github.com/fluent/fluent-logger-golang/

Depois, use o código como o demonstrado a seguir para enviar dados do erro:

package main

import (
	"log"
	"net/http"
	"os"
	"runtime"

	"github.com/fluent/fluent-logger-golang/fluent"
)

var logger *fluent.Fluent

func main() {
	var err error
	logger, err = fluent.New(fluent.Config{
		FluentHost: "localhost",
		FluentPort: 24224,
	})
	if err != nil {
		log.Fatal(err)
	}

	http.HandleFunc("/demo", demoHandler)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	log.Printf("Listening on port %s", port)
	if err := http.ListenAndServe(":"+port, nil); err != nil {
		log.Fatal(err)
	}
}

func report(stackTrace string, r *http.Request) {
	payload := map[string]interface{}{
		"serviceContext": map[string]interface{}{
			"service": "myapp",
		},
		"message": stackTrace,
		"context": map[string]interface{}{
			"httpRequest": map[string]interface{}{
				"method":    r.Method,
				"url":       r.URL.String(),
				"userAgent": r.UserAgent(),
				"referrer":  r.Referer(),
				"remoteIp":  r.RemoteAddr,
			},
		},
	}
	if err := logger.Post("myapp.errors", payload); err != nil {
		log.Print(err)
	}
}

// Handler for the incoming requests.
func demoHandler(w http.ResponseWriter, r *http.Request) {
	// How to handle a panic.
	defer func() {
		if e := recover(); e != nil {
			stack := make([]byte, 1<<16)
			stackSize := runtime.Stack(stack, true)
			report(string(stack[:stackSize]), r)
		}
	}()

	// Panic is triggered.
	x := 0
	log.Println(100500 / x)
}

Usar a API Error Reporting para gravar erros

A API Error Reporting fornece um endpoint report para gravar informações de erro no serviço.

1. Ative a API Error Reporting, se ela ainda não estiver ativada.

   Funções necessárias para ativar APIs

   Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

   Ativar a API

2. Informe erros na API usando a API REST ou uma biblioteca de cliente.

   • API REST

     Confira a documentação de referência para mais informações sobre a API.

   • Como usar bibliotecas de cliente

     Há algumas linguagens que dispõem de bibliotecas para ajudar você a chamar a API Error Reporting a partir do seu aplicativo:

     • ASP.NET
     • Go
     • Java
     • Node.js
     • Ruby
     • Python
     • PHP

Amostras

ASP.NET

O pacote NuGet do ASP.NET informa exceções não capturadas de aplicativos da Web ASP.NET ao Error Reporting.

Instalar o pacote NuGet

Para instalar o pacote NuGet para ASP.NET do Stackdriver no Visual Studio:

1. Clique com o botão direito do mouse em sua solução e selecione Gerenciar pacotes NuGet para solução.
2. Marque a caixa de seleção Incluir pré-lançamento.
3. Pesquise e instale o pacote Google.Cloud.Diagnostics.AspNet.

Uso

Depois de instalar o pacote NuGet do Stackdriver ASP.NET, adicione a instrução a seguir ao código do aplicativo para começar a enviar erros ao Stackdriver:

using Google.Cloud.Diagnostics.AspNet;

Adicione o seguinte código HttpConfiguration ao método Register do seu app da Web .NET depois de substituir your-project-id pelo seu ID do projeto para ativar a geração de relatórios de exceções:

public static void Register(HttpConfiguration config)
{
    string projectId = "YOUR-PROJECT-ID";
    string serviceName = "NAME-OF-YOUR-SERVICE";
    string version = "VERSION-OF-YOUR-SERVCICE";
    // ...
    // Add a catch all for the uncaught exceptions.
    config.Services.Add(typeof(IExceptionLogger),
        ErrorReportingExceptionLogger.Create(projectId, serviceName, version));
    // ...
}

Depois de adicionar esse método ao aplicativo ASP.NET, você pode conferir as exceções não capturadas que ocorrem à medida que são informadas ao Google Cloud na seção Error Reporting do console Google Cloud .

C#

O exemplo a seguir pode ser encontrado no repositório GoogleCloudPlatform/dotnet-docs-samples. Para usar, depois de criar o projeto, especifique o ID do projeto:

C:\...\bin\Debug> set GOOGLE_PROJECT_ID=[YOUR_PROJECT_ID]

Substitua [YOUR_PROJECT_ID] pelo valor correto do consoleGoogle Cloud .

Em seguida, envie os dados da exceção com um código semelhante a este:

public class ErrorReportingSample
{
    public static void Main(string[] args)
    {
        try
        {
            throw new Exception("Generic exception for testing Stackdriver Error Reporting");
        }
        catch (Exception e)
        {
            report(e);
            Console.WriteLine("Stackdriver Error Report Sent");
        }
    }

    /// <summary>
    /// Create the Error Reporting service (<seealso cref="ClouderrorreportingService"/>)
    /// with the Application Default Credentials and the proper scopes.
    /// See: https://developers.google.com/identity/protocols/application-default-credentials.
    /// </summary>
    private static ClouderrorreportingService CreateErrorReportingClient()
    {
        // Get the Application Default Credentials.
        GoogleCredential credential = GoogleCredential.GetApplicationDefaultAsync().Result;

        // Add the needed scope to the credentials.
        credential.CreateScoped(ClouderrorreportingService.Scope.CloudPlatform);

        // Create the Error Reporting Service.
        ClouderrorreportingService service = new ClouderrorreportingService(new BaseClientService.Initializer
        {
            HttpClientInitializer = credential,
        });
        return service;
    }

    /// <summary>
    /// Creates a <seealso cref="ReportRequest"/> from a given exception.
    /// </summary>
    private static ReportRequest CreateReportRequest(Exception e)
    {
        // Create the service.
        ClouderrorreportingService service = CreateErrorReportingClient();

        // Get the project ID from the environement variables.
        string projectId = Environment.GetEnvironmentVariable("GOOGLE_PROJECT_ID");

        // Format the project id to the format Error Reporting expects. See:
        // https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events/report
        string formattedProjectId = string.Format("projects/{0}", projectId);

        // Add a service context to the report.  For more details see:
        // https://cloud.google.com/error-reporting/reference/rest/v1beta1/projects.events#ServiceContext
        ServiceContext serviceContext = new ServiceContext()
        {
            Service = "myapp",
            Version = "8c1917a9eca3475b5a3686d1d44b52908463b989",
        };
        ReportedErrorEvent errorEvent = new ReportedErrorEvent()
        {
            Message = e.ToString(),
            ServiceContext = serviceContext,
        };
        return new ReportRequest(service, errorEvent, formattedProjectId);
    }

    /// <summary>
    /// Report an exception to the Error Reporting service.
    /// </summary>
    private static void report(Exception e)
    {
        // Create the report and execute the request.
        ReportRequest request = CreateReportRequest(e);
        request.Execute();
    }
}

Go

Consulte Como configurar o Error Reporting para Go.

Java

Consulte Como configurar o Error Reporting para Java.

Node.js

Consulte Como configurar o Error Reporting para Node.js.

Ruby

Consulte Como configurar o Error Reporting para Ruby.

Python

Consulte Como configurar o Error Reporting para Python.

PHP

Veja Como configurar o Error Reporting para PHP.

Ver grupos de erros

No console Google Cloud , acesse a página Error Reporting:

Acessar o Error Reporting

Também é possível encontrar essa página usando a barra de pesquisa.

Observação: se a mensagem "Configurar o Error Reporting" aparecer na página Error Reporting, seu projeto Google Cloud não tem grupos de erros para mostrar.