Neste documento, explicamos como formatar a entrada de registro quando você quiser usar o Cloud Logging para relatar eventos de erro.
É possível relatar eventos de erro para seu projeto do Google Cloud
executando o método da API Cloud Logging
write
ou o método
report
da API Error Reporting.
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 de acordo com seu idioma e sua plataforma.
Se você exigir a autenticação baseada em chave de API, será necessário usar a API Error Reporting. Para informar 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 objetoReportedErrorEvent
.Quando você usa 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 com
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
, é possível que você receba cobranças de ingestão do Cloud Logging. Para controlar quais registros são ingeridos, consulte Filtros de exclusão.Se você relatar eventos de erro usando a API Error Reporting, o restante deste documento não se aplicará.
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 é um stack trace, grave o evento de erro como um destes tipos:
- Um
textPayload
de várias linhas. Um
jsonPayload
que inclui um campomessage
,stack_trace
ouexception
.É possível especificar mais de um desses campos. Se mais de um desses campos for especificado, a ordem de avaliação será:
stack_trace
,exception
emessage
.Se o evento de erro estiver formatado como um objeto
ReportedErrorEvent
, copie os campos para ojsonPayload
. Para mais informações e um exemplo, consulte Registrar um erro formatado como um objetoReportedErrorEvent
.Um
jsonPayload
que não inclui um campomessage
,stack_trace
ouexception
, mas inclui um stack trace.O Error Reporting pesquisa todos os campos em um
jsonPayload
em busca de stack traces. Se mais de um stack trace for encontrado, um de pilha será selecionado. O algoritmo de seleção garante uma escolha consistente.
Registrar uma mensagem de texto
Para registrar um evento de erro que é 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
como 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 não defini-lo,
o Cloud Logging
vai procurar o campo rotulado 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
tiverem um stack trace.
Nesses casos, o Error Reporting captura automaticamente o evento de erro.
Recursos monitorados com suporte
Defina o campo resource
do objeto LogEntry
como um destes
tipos de recursos monitorados com suporte:
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_job
1workflows.googleapis.com/Workflow
global
1
1textPayload
não é compatível
Examples
Nesta seção, mostramos como garantir que o Error Reporting processe uma entrada de registro quando ela contiver uma mensagem de texto ou um stack trace.
Registrar um evento de erro que seja uma mensagem de texto
No exemplo a seguir, mostramos como formatar um objeto LogEntry
quando você
quiser registrar 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 o exemplo, você precisa definir o campo @type
como 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
.
Registra um erro formatado como um objeto ReportedErrorEvent
Quando o evento de erro for armazenado em um objeto ReportedErrorEvent
, use a seguinte estrutura JSON para o campo jsonPayload
de
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
da
LogEntry
a ser formatada 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" }
Registre um evento de erro usando o campo textPayload
É possível registrar um evento de erro usando o campo textPayload
de um LogEntry
para armazenar os dados do erro. Por exemplo,
o comando da Google Cloud CLI a seguir resulta em uma entrada de registro com
nível de gravidade ERROR
e campo textPayload
que 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 pelo 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)" ... }