Erros de formato nos registos

Este documento explica como formatar a entrada de registo quando quiser usar o Cloud Logging para comunicar eventos de erro.

Pode comunicar eventos de erro ao seu Google Cloud projeto executando o método da API Cloud Logging write ou o método da API Error Reporting report. Quando comunica eventos de erro através da API Cloud Logging, o corpo do pedido contém um objeto LogEntry que tem de incluir um rastreio da pilha ou um objeto ReportedErrorEvent.

Antes de começar

  • Siga as instruções de configuração para o seu idioma e plataforma.

  • Se precisar de autenticação baseada em chaves de API, tem de usar a API Error Reporting. Para comunicar um evento de erro através da API Error Reporting, execute o método report e formate o corpo do pedido do método como um objeto ReportedErrorEvent.

    Quando usa a API Error Reporting, as entradas de registo com mensagens de erro formatadas corretamente são geradas e escritas automaticamente no Cloud Logging. Estas entradas de registo são escritas num registo cujo logName está formatado da seguinte forma:

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

    Uma vez que as entradas de registo são geradas por chamadas para report, pode incorrer em custos de carregamento do Cloud Logging. Para controlar que registos são carregados, consulte os filtros de exclusão.

    Se comunicar eventos de erro através da API Error Reporting, o resto deste documento não se aplica.

Requisitos de formato LogEntry

Esta secção descreve como formatar um LogEntry para que os Relatórios de erros capturem o evento de erro contido na entrada do registo.

Registe um rastreio de pilha

Para registar um evento de erro que seja um rastreio da pilha, escreva o evento de erro como um destes tipos:

  • Uma linha múltipla textPayload.

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

    Pode especificar mais do que um desses campos. Se for especificado mais do que um desses campos, a ordem de avaliação é: stack_trace, exception e, em seguida, message.

    Se o campo de mensagem for avaliado e não estiver vazio, o rastreio da pilha só é capturado quando o campo contém um rastreio da pilha num dos formatos de linguagem de programação suportados. O rastreio da pilha não é capturado pelo relatório de erros quando é usado um formato não suportado.

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

  • Um jsonPayload que não inclui um campo message, stack_trace ou exception, mas inclui um rastreio de pilha.

    A comunicação de erros pesquisa todos os campos num jsonPayload para rastreios de pilha. Se forem encontradas mais do que uma rastreabilidade da pilha, é selecionada uma rastreabilidade da pilha. O algoritmo de seleção garante uma escolha consistente.

Registe uma mensagem de texto

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

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

Quando define o campo @type para o valor especificado, o Relatório de erros avalia sempre a entrada do registo como se todos os campos obrigatórios estivessem presentes. Como resultado, o Relatório de erros captura o evento de erro.

Se definir o campo @type para um valor diferente ou o deixar não definido, o Cloud Logging procura o campo etiquetado como serviceContext para determinar se a carga útil é um objeto ReportedErrorEvent.

Não tem de definir o campo @type quando os campos message, stack_trace, ou exception do jsonPayload contêm um rastreio da pilha. Nesses casos, o Relatório de erros captura automaticamente o evento de erro.

Recursos monitorizados suportados

Defina o campo resource do objeto LogEntry para um dos seguintes tipos de recursos monitorizados suportados:

  • 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

1 textPayload não suportado

Exemplos

Esta secção mostra como pode garantir que o Relatório de erros processa uma entrada de registo quando essa entrada de registo contém uma mensagem de texto ou um rastreio de pilha.

Registe um evento de erro que seja uma mensagem de texto

O exemplo seguinte mostra como formatar um objeto LogEntry quando quiser registar um evento de erro que seja 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"
  }
}

Conforme mostra o exemplo, tem de definir o campo @type para o valor que força o relatório de erros a agrupar a entrada do registo: Para mais informações, consulte Registe uma mensagem de texto.

Quando o campo message contém um rastreio da pilha, a entrada do registo é agrupada automaticamente, pelo que não precisa de especificar o campo @type.

Registe um erro formatado como um objeto ReportedErrorEvent

Quando o evento de erro é armazenado num 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
    }
  }
}

Certifique-se de que preenche o campo message com as informações de erro. Para saber como armazenar um rastreio de pilha no campo message de um objeto ReportedErrorEvent, consulte a página de referência do método report.

O exemplo seguinte ilustra como definir o campo jsonPayload do elemento LogEntry para ser formatado como um objeto ReportedErrorEvent. Uma vez que o campo message contém um rastreio da pilha, o evento de erro é agrupado por Relatórios de erros:

{...
   "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"
}

Registe um evento de erro através do campo textPayload

Pode registar um evento de erro usando o campo textPayload de um LogEntry para armazenar os dados de erro. Por exemplo, o seguinte comando da CLI do Google Cloud resulta numa entrada de registo 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 registo agrupada por Relatório de erros:

{...
    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)"
    ...
}