En este documento, se explica cómo dar formato a la entrada de registro cuando deseas usar Cloud Logging para informar sobre eventos de errores.
Puedes informar eventos de error a tu proyecto de Google Cloud ejecutando el método write
de la API de Cloud Logging o el método report
de la API de Error Reporting.
Cuando informas eventos de error con la API de Cloud Logging, el cuerpo de la solicitud
contiene un objeto LogEntry
que debe incluir un seguimiento de pila o un objeto ReportedErrorEvent
.
Antes de comenzar
Sigue las instrucciones de configuración para tu lenguaje y plataforma.
Si necesitas autenticación basada en claves de API, debes usar la API de Error Reporting. Para informar un evento de error con la API de Error Reporting, ejecuta el método
report
y da formato al cuerpo de la solicitud del método como un objetoReportedErrorEvent
.Cuando usas la API de Error Reporting, las entradas de registro con mensajes de error con el formato correcto se generan y escriben automáticamente en Cloud Logging. Estas entradas de registro se escriben en un registro cuyo
logName
tiene el siguiente formato:projects/PROJECT_ID/clouderrorreporting.googleapis.com%2Freported_errors
Debido a que las entradas de registro se generan a través de llamadas a
report
, es posible que incurras en costos de transferencia de Cloud Logging. Para controlar qué registros se transfieren, consulta Filtros de exclusión.Si informas eventos de error con la API de Error Reporting, el resto de este documento no se aplica.
Requisitos de formato LogEntry
En esta sección, se describe cómo dar formato a un LogEntry
para que Error Reporting capture el evento de error que se incluye en la entrada de registro.
Cómo registrar un seguimiento de pila
Para registrar un evento de error que es un seguimiento de pila, escribe el evento de error como uno de estos tipos:
- Es un
textPayload
de varias líneas. Un
jsonPayload
que incluye un campomessage
,stack_trace
oexception
Puedes especificar más de uno de esos campos. Si se especifica más de uno de esos campos, el orden de la evaluación es este:
stack_trace
,exception
y, por último,message
.Si se evalúa el campo de mensaje y no está vacío, el seguimiento de pila se captura solo cuando el campo contiene un seguimiento de pila en uno de los formatos de lenguaje de programación admitidos. Error Reporting no captura el seguimiento de pila cuando se usa un formato no compatible.
Si el evento de error tiene el formato de un objeto
ReportedErrorEvent
, copia sus campos enjsonPayload
. Para obtener más información y un ejemplo, consulta Cómo registrar un error con formato de objetoReportedErrorEvent
.Un
jsonPayload
que no incluye un campomessage
,stack_trace
niexception
, pero que incluye un seguimiento de pilaError Reporting busca trazas de pila en todos los campos de un
jsonPayload
. Si se encuentra más de un seguimiento de pila, se selecciona uno. El algoritmo de selección garantiza una elección coherente.
Cómo registrar un mensaje de texto
Para registrar un evento de error que es un mensaje de texto, usa el siguiente formato para el jsonPayload
:
"jsonPayload": { "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent", "message": "Text message" },
Cuando configuras el campo @type
en el valor especificado, Error Reporting siempre evalúa la entrada de registro como si todos los campos obligatorios estuvieran presentes. Como resultado,
Error Reporting captura el evento de error.
Si estableces el campo @type
en un valor diferente o no lo estableces, Cloud Logging busca el campo etiquetado como serviceContext
para determinar si la carga útil es un objeto ReportedErrorEvent
.
No es necesario que configures el campo @type
cuando los campos message
, stack_trace
o exception
de jsonPayload
contengan un seguimiento de pila.
En esos casos, Error Reporting captura automáticamente
el evento de error.
Recursos supervisados compatibles
Establece el campo resource
del objeto LogEntry
en uno de los siguientes tipos de recursos supervisados compatibles:
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
1 textPayload
no compatible
Ejemplos
En esta sección, se muestra cómo puedes asegurarte de que el Error Reporting procese una entrada de registro cuando esta contenga un mensaje de texto o un seguimiento de pila.
Cómo registrar un evento de error que es un mensaje de texto
En el siguiente ejemplo, se muestra cómo dar formato a un objeto LogEntry
cuando quieres registrar un evento de error que es un mensaje de texto. Usa la siguiente estructura JSON para el campo jsonPayload
de 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 se muestra en el ejemplo, debes establecer el campo @type
en el valor que obliga a que el Error Reporting agrupe la entrada de registro: Para obtener más información, consulta Cómo registrar un mensaje de texto.
Cuando el campo message
contiene un seguimiento de pila, la entrada de registro se agrupa automáticamente, por lo que no necesitas especificar el campo @type
.
Registra un error con formato de objeto ReportedErrorEvent
Cuando el evento de error se almacena en un objeto ReportedErrorEvent
, usa la siguiente estructura JSON para el 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 } } }
Asegúrate de propagar el campo message
con la información del error.
Para aprender a almacenar un seguimiento de pila en el campo message
de un objeto ReportedErrorEvent
, consulta la página de referencia del método report
.
En el siguiente ejemplo, se muestra cómo configurar el campo jsonPayload
de LogEntry
para que tenga el formato de un objeto ReportedErrorEvent
.
Debido a que el campo message
contiene un seguimiento de pila,
Error Reporting agrupa el evento de error:
{... "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" }
Registra un evento de error con el campo textPayload
Puedes registrar un evento de error con el campo textPayload
de un LogEntry
para almacenar los datos del error. Por ejemplo, el siguiente comando de Google Cloud CLI genera una entrada de registro cuyo nivel de gravedad es ERROR
y cuyo campo textPayload
contiene un evento de error:
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)'
El resultado del comando anterior es una entrada de registro que se agrupa 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)" ... }