Erros de formatação em registros

Nesta página, você entenderá qual é o formato de entrada de registro necessário para usar o Cloud Logging para relatar eventos de erro.

Antes de começar

Se estiver usando a API Error Reporting, será possível relatar eventos de erro a partir do seu aplicativo gravando-os em ReportedErrorEvent (em inglês). Isso gera entradas de registro com mensagens de erro formatadas adequadamente no Cloud Logging. O logName resultante é formatado como:

  projects/<PROJECT_ID>/clouderrorreporting.googleapis.com%2Freported_errors

Ao usar este método, poderá haver cobranças por processamento no Cloud Logging. Para controlar os custos, reveja Exclusões de registros.

Se você preferir usar o Cloud Logging para relatar eventos de erro, leia as seções a seguir.

Requisitos de formatação

As entradas de registro no Cloud Logging que contêm stack traces ou exceções, ou que são formatadas como ReportedErrorEvent (em inglês), geram erros no Error Reporting.

Os dados de erro devem ser registrados no campo de união LogEntry payload como um destes tipos:

  • uma multilinha textPayload;
  • o campo message de jsonPayload.

Você também precisa seguir as instruções de configuração para sua plataforma e linguagem. Ao registrar dados de erros do App Engine, Compute Engine e Google Kubernetes Engine, o único requisito de formatação é que a entrada de registro contenha stack trace e mensagem completas de exceção.

Para saber como formatar stack trace e mensagem de exceção, vá para a seção ReportedErrorEvent na página de referência report do Error Reporting.

Como especificar @type

Se a entrada de registro tiver @type de type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent, o Error Reporting avaliará a entrada de registro como se todos os campos obrigatórios estivessem presentes e identificará o evento de erro.

Representação JSON

Ao enviar dados de erro usando o Cloud Logging, o ReportedErrorEvent fornecido precisa usar a seguinte estrutura JSON:

    {
      "eventTime": string,
      "serviceContext": {
        "service": string,     // Required.
        "version": string
      },
      "message": string,       // Required. Should contain the full exception
                               // message, including the stack trace.
      "@type": string          // Optional.  Review "Specifying @type" section above.
      "context": {
        "httpRequest": {
          "method": string,
          "url": string,
          "userAgent": string,
          "referrer": string,
          "responseStatusCode": number,
          "remoteIp": string
        },
        "user": string,
        "reportLocation": {    // Required if no stack trace is provided.
          "filePath": string,
          "lineNumber": number,
          "functionName": string
        }
      }
    }

Tipos de recursos monitorados compatíveis

Ao fazer login por meio da estrutura LogEntry, o campo resource deve ser definido como um dos seguintes tipos de recursos monitorados (em inglês) compatíveis:

  • app_script_function
  • aws_ec2_instance
  • cloud_function
  • cloud_run_revision
  • consumed_api
  • container
  • dataflow_step
  • gae_app
  • gce_instance
  • k8s_container
  • ml_job1
  • global1

1textPayloadnão é compatível

Exemplos de formatação de entrada de registro

Os exemplos a seguir ilustram entradas de registro que são processadas corretamente pelo Error Reporting se forem registradas em LogEntry.jsonPayload.

Esta entrada de registro está agrupada porque o @type está especificado de forma adequada:

{...
  {
    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "An error message without stacktrace or exception"
    },
    "logName": "projects/test-project/logs/reported-error",
    "resource": {
      "labels": {
        "project_id": "test-project"
      },
      "type": "global"
    },
    "severity": "ERROR",
    "timestamp": "2019-06-27T13:43:26.375834551Z"
  }
}

A message do payload desta entrada de registro contém um stack trace e uma exceção. Portanto, ela também é agrupada pelo Error Reporting:

{
      "serviceContext": {
        "service": "frontend",
        "version": "bf6b5b09b9d3da92c7bf964ab1664fe751104517"
      },
      "message": "com.example.shop.Template$CartDiv retrieveCart: Error\njava.lang.IndexOutOfBoundsException: Index: 4, Size: 4\n\tat java.util.ArrayList.rangeCheck(ArrayList.java:635)\n\tat java.util.ArrayList.get(ArrayList.java:411)\n\tat com.example.shop.Cart.retrieve(Cart.java:76)\n\tat com.example.shop.Cart.generate(Cart.java:55)\n\tat com.example.shop.Template$CartDiv.retrieveCart(Template.java:113)\n\tat com.example.shop.Template.generate(Template.java:22)\n\tat com.example.shop.CartServlet.doGet(CartServlet.java:115)\n\tat javax.servlet.http.HttpServlet.service(HttpServlet.java:717)\n",
      "context": {
        "httpRequest": {
          "method": "GET",
          "url": "http://example.com/shop/cart",
          "responseStatusCode": 500
        },
        "user": "9f32f587135aa6774e78ed30fbaabcce3ec5528f"
      }
    }

Para detalhes sobre os campos usados em uma instância de ReportedErrorEvent, consulte a documentação (em inglês).