Errores de formato en los registros

En este documento, se explica cómo dar formato a la entrada de registro cuando quieres usar Cloud Logging para informar eventos de errores.

Puedes informar eventos de errores a tu proyecto de Google Cloud de la siguiente manera: ejecutar el método de la API de Cloud Logging write o el método de la API de Error Reporting report Cuando informes eventos de error con la API de Cloud Logging, 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 una 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 objeto ReportedErrorEvent.

    Cuando uses la API de Error Reporting, registra entradas los mensajes de error con formato 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 errores con la API de Error Reporting, el resto de este documento no se aplica.

Requisitos de formato de LogEntry

En esta sección, se describe cómo darle formato a una LogEntry para que Error Reporting captura el evento de error que contiene en la entrada de registro.

Cómo registrar un seguimiento de pila

Para registrar un evento de error que sea un seguimiento de pila, escribe el error como uno de estos tipos:

  • Una textPayload de varias líneas.

  • Un jsonPayload que incluya un message, stack_trace o exception .

    Puedes especificar más de uno de esos campos. Si hay más de uno de esos si se especifican campos, el orden de evaluación es el siguiente: stack_trace, luego exception y, después, message.

    Si el evento de error tiene el formato de un objeto ReportedErrorEvent, copia sus campos en jsonPayload. Para obtener más información y un ejemplo, consulta Registra un error que tenga el formato de un objeto ReportedErrorEvent.

  • Un jsonPayload que no incluye message, stack_trace ni exception, pero incluye un seguimiento de pila.

    Error Reporting busca en todos los campos de un jsonPayload seguimientos de pila. Si se encuentra más de un seguimiento de pila, entonces hay una pila. un registro seleccionado. El algoritmo de selección garantiza una elección coherente.

Registrar un mensaje de texto

Si quieres registrar un evento de error que sea 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 estuvieran todos los campos obligatorios. Como resultado, Error Reporting captura el evento de error.

Si configuras el campo @type con un valor diferente o no lo estableces, entonces Cloud Logging busca el campo etiquetado serviceContext para determinar si la carga útil Un objeto ReportedErrorEvent

No es necesario que configures el campo @type cuando las variables message, stack_trace o exception de jsonPayload contienen 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 una de las siguientes plataformas tipos de recursos supervisados:

  • 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 no compatible

Ejemplos

En esta sección, se muestra cómo puedes que Error Reporting procese una entrada de registro cuando una entrada de registro que contenga un mensaje de texto o un seguimiento 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 si deseas registrar un evento de error que sea un mensaje de texto, usa el 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 configurar el campo @type en el valor que fuerza Error Reporting para agrupar la entrada de registro: Para obtener más información, consulta Registra 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 que tenga el formato de un objeto ReportedErrorEvent.

Cuando el evento de error se almacena en una 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 la LogEntry se formateará como 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

Para registrar un evento de error, utiliza el campo textPayload de una 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 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)"
    ...
}