En este documento se explica cómo dar formato a la entrada de registro cuando quieras usar Cloud Logging para informar de eventos de error.
Puedes informar de eventos de error a tu Google Cloud proyecto ejecutando el método de la API Cloud Logging write
o el método de la API Error Reporting report
.
Cuando informas de eventos de error mediante 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 empezar
Sigue las instrucciones de configuración para tu idioma y plataforma.
Si necesitas la autenticación basada en claves de API, debes usar la API Error Reporting. Para registrar un evento de error mediante la API 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 Error Reporting, se generan automáticamente entradas de registro con mensajes de error con el formato adecuado y se escriben 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
Como las entradas de registro se generan mediante llamadas a
report
, es posible que se te apliquen costes de ingestión de Cloud Logging. Para controlar qué registros se ingieren, consulta la sección sobre filtros de exclusión.Si informa de eventos de error mediante la API 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 registre el evento de error que contiene la entrada de registro.
Registrar un rastreo de la pila
Para registrar un evento de error que sea un seguimiento de pila, escribe el evento de error como uno de estos tipos:
- Un
textPayload
de varias líneas. Un
jsonPayload
que incluye un campomessage
,stack_trace
oexception
.Puede especificar más de uno de esos campos. Si se especifica más de uno de estos campos, el orden de evaluación es el siguiente:
stack_trace
,exception
ymessage
.Si se evalúa el campo de mensaje y no está vacío, la traza de pila se captura solo cuando el campo contiene una traza 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 admitido.
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 Registrar un error con el formato de un objetoReportedErrorEvent
.Un
jsonPayload
que no incluye los camposmessage
,stack_trace
niexception
, pero sí incluye un rastreo de la pila.Informes de errores busca en todos los campos de un
jsonPayload
para rastrear la pila. Si se encuentra más de un rastreo de pila, se selecciona uno. El algoritmo de selección asegura una elección coherente.
Registrar un mensaje de texto
Para registrar un evento de error que sea un mensaje de texto, usa el siguiente formato para jsonPayload
:
"jsonPayload": { "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent", "message": "Text message" },
Cuando asignas al campo @type
el valor especificado, Error Reporting siempre evalúa la entrada de registro como si estuvieran presentes todos los campos obligatorios. Como resultado, Error Reporting captura el evento de error.
Si asigna al campo @type
otro valor o no lo define, Cloud Logging buscará el campo etiquetado como serviceContext
para determinar si la carga útil es un objeto ReportedErrorEvent
.
No es necesario que defina 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 monitorizados admitidos
En el campo resource
del objeto LogEntry
, introduzca uno de los siguientes tipos de recursos monitorizados:
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 admitido
Ejemplos
En esta sección se muestra cómo puede asegurarse de que Error Reporting procese una entrada de registro cuando esta contenga un mensaje de texto o un rastreo de pila.
Registra un evento de error que sea un mensaje de texto
En el siguiente ejemplo se muestra cómo dar formato a un objeto LogEntry
cuando quieras registrar un evento de error que sea un mensaje de texto. Para ello, usa la siguiente estructura JSON en el campo jsonPayload
del 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, debe definir el campo @type
con el valor que obliga a Error Reporting a agrupar la entrada de registro:
Para obtener más información, consulte 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 es necesario especificar el campo @type
.
Registra un error con el formato de un objeto ReportedErrorEvent
Si el evento de error se almacena en un objeto ReportedErrorEvent
, use la siguiente estructura JSON para el campo jsonPayload
del
objeto 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úrese de rellenar el campo message
con la información del error.
Para saber cómo 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 definir el campo jsonPayload
de LogEntry
para que se le dé formato de objeto ReportedErrorEvent
.
Como 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" }
Registrar un evento de error mediante el campo textPayload
Puedes registrar un evento de error usando el campo textPayload
de un LogEntry
para almacenar los datos del error. Por ejemplo, el siguiente comando de la CLI de Google Cloud 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 agrupada por Informes de errores:
{... 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)" ... }