Formatar uma entrada de registro para informar eventos de erro

Neste documento, explicamos como formatar a entrada de registro quando você quer usar o Cloud Logging para informar eventos de erro.

Para informar eventos de erro ao seu projeto Google Cloud , execute o método da API Cloud Logging write ou o método da API Error Reporting report. Ao relatar eventos de erro usando a API Cloud Logging, o corpo da solicitação contém um objeto LogEntry que precisa incluir um stack trace ou um objeto ReportedErrorEvent.

Antes de começar

  • Siga as instruções de configuração para sua plataforma e linguagem.

  • Se você precisar de autenticação baseada em chave de API, use a API Error Reporting. Para relatar um evento de erro usando a API Error Reporting, execute o método report e formate o corpo da solicitação do método como um objeto ReportedErrorEvent.

    Ao usar a API Error Reporting, as entradas de registro com mensagens de erro formatadas corretamente são geradas e gravadas automaticamente no Cloud Logging. Essas entradas de registro são gravadas em um registro cujo logName é formatado da seguinte maneira:

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

    Como as entradas de registro são geradas por chamadas para report, você pode ter custos de ingestão do Cloud Logging. Para controlar quais entradas de registro são ingeridas, consulte Filtros de exclusão.

    Se você relatar eventos de erro usando a API Error Reporting, o restante deste documento não será aplicável.

Requisitos de formato do LogEntry

Nesta seção, descrevemos como formatar um LogEntry para que o Error Reporting capture o evento de erro contido na entrada de registro.

Registrar um stack trace

Para registrar um evento de erro que seja um stack trace, escreva o evento de erro como um destes tipos:

  • Uma multilinha textPayload.

  • Um jsonPayload que inclui um campo message, stack_trace ou exception.

    É possível especificar mais de um desses campos. Se mais de um desses campos for especificado, a ordem de avaliação será: stack_trace, depois exception e, em seguida, message.

    Se o campo de mensagem for avaliado e não estiver vazio, o stack trace será capturado somente quando o campo contiver um stack trace em um dos formatos de linguagem de programação compatíveis. O stack trace não é capturado pelo Error Reporting quando um formato sem suporte é usado.

    Se o evento de erro estiver formatado como um objeto ReportedErrorEvent, copie os campos dele para o jsonPayload. Para mais informações e um exemplo, consulte Registrar um erro formatado como um objeto ReportedErrorEvent.

  • Um jsonPayload que não inclui um campo message, stack_trace ou exception, mas inclui um stack trace.

    O Error Reporting pesquisa todos os campos em um jsonPayload para rastreamentos de pilha. Se mais de um stack trace for encontrado, um deles será selecionado. O algoritmo de seleção garante uma escolha consistente.

Registrar uma mensagem de texto

Para registrar um evento de erro que seja uma mensagem de texto, use o seguinte formato para o jsonPayload:

    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "Text message"
    },

Quando você define o campo @type com o valor especificado, o Error Reporting sempre avalia a entrada de registro como se todos os campos obrigatórios estivessem presentes. Como resultado, o Error Reporting captura o evento de erro.

Se você definir o campo @type com um valor diferente ou deixar sem definição, o Cloud Logging vai procurar o campo serviceContext para determinar se o payload é um objeto ReportedErrorEvent.

Não é necessário definir o campo @type quando os campos message, stack_trace ou exception do jsonPayload contêm um stack trace. Nesses casos, o Error Reporting captura automaticamente o evento de erro.

Recursos monitorados compatíveis

Defina o campo resource do objeto LogEntry como um dos seguintes tipos de recursos monitorados (em inglês) compatíveis:

  • app_script_function
  • aws_ec2_instance
  • cloud_function
  • cloud_run_jobs
  • cloud_run_revision
  • consumed_api
  • container
  • dataflow_step
  • gae_app
  • gce_instance
  • k8s_container
  • k8s_pod
  • ml_job1
  • workflows.googleapis.com/Workflow
  • global1

1textPayloadnão é compatível

Exemplos

Esta seção mostra como garantir que o Error Reporting processe uma entrada de registro quando ela contém uma mensagem de texto ou um stack trace.

Registrar um evento de erro que é uma mensagem de texto

O exemplo a seguir mostra como formatar um objeto LogEntry quando você quer registrar um evento de erro que é uma mensagem de texto. Use a seguinte estrutura JSON para o campo jsonPayload do LogEntry:

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

Como mostrado no exemplo, você precisa definir o campo @type com o valor que força o Error Reporting a agrupar a entrada de registro: Para mais informações, consulte Registrar uma mensagem de texto.

Quando o campo message contém um stack trace, a entrada de registro é agrupada automaticamente para que você não precise especificar o campo @type.

Registrar um erro formatado como um objeto ReportedErrorEvent

Quando o evento de erro é armazenado em um objeto ReportedErrorEvent, use a seguinte estrutura JSON para o campo jsonPayload do LogEntry:

{
  "eventTime": string,
  "serviceContext": {
    "service": string,     // Required.
    "version": string
  },
  "message": string,       // Required. This field contains the main error content to report.
  "@type": string          // Optional. For information about this field, see Log a text message.
  "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
    }
  }
}

Preencha o campo message com as informações do erro. Para saber como armazenar um stack trace no campo message de um objeto ReportedErrorEvent, consulte a página de referência do método report.

O exemplo a seguir ilustra como definir o campo jsonPayload do LogEntry para ser formatado como um objeto ReportedErrorEvent. Como o campo message contém um stack trace, o evento de erro é agrupado pelo Error Reporting:

{...
   "jsonPayload": {
      "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"
      }
   },
   "logName": "projects/test-project/logs/reported-error",
   "resource": {
      "labels": {
        "project_id": "test-project"
      },
      "type": "global"
   },
   "severity": "ERROR",
   "timestamp": "2019-06-27T13:43:26.375834551Z"
}

Registrar um evento de erro usando o campo textPayload

É possível registrar um evento de erro usando o campo textPayload de um LogEntry para armazenar a mensagem de erro, como um stack trace. Por exemplo, o comando da Google Cloud CLI a seguir resulta em uma entrada de registro cujo nível de gravidade é ERROR e cujo campo textPayload contém um evento de erro:

gcloud logging write test-log --severity=ERROR --payload-type=text 'RuntimeException: Oops! Something bad happened.
at com.example.MyClass.method(MyClass.java:123)
at com.example.OtherClass.doStuff(Unknown Source)
at com.example.Sys.create(Native Method)'

O resultado do comando anterior é uma entrada de registro agrupada por Error Reporting:

{...
    logName: "projects/PROJECT_ID/logs/test-log"
    severity: "ERROR"
    textPayload: "RuntimeException: Oops! Something bad happened.
                  at com.example.MyClass.method(MyClass.java:123)
                  at com.example.OtherClass.doStuff(Unknown Source)
                  at com.example.Sys.create(Native Method)"
    ...
}