Cómo dar formato a una entrada de registro para informar eventos de errores

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 de la API de Cloud Loggingwrite o el método de la API de Error Reportingreport. 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 formatea el cuerpo de la solicitud del método como un objeto ReportedErrorEvent.

    Cuando usas la API de Error Reporting, se generan automáticamente entradas de registro con mensajes de error con el formato correcto 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

    Dado que las entradas de registro se generan a partir de llamadas a report, es posible que incurras en costos de transferencia de Cloud Logging. Para controlar qué entradas de registro se transfieren, consulta Filtros de exclusión.

    Si informas eventos de errores con la API de Error Reporting, no se aplica el resto de este documento.

Requisitos de formato de 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 sea un seguimiento de pila, escribe el evento de error como uno de estos tipos:

  • Es una textPayload de varias líneas.

  • Es un jsonPayload que incluye un campo message, stack_trace o exception.

    Puedes especificar más de uno de esos campos. Si se especifica más de uno de esos campos, el orden de evaluación es el siguiente: 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 tu evento de error tiene el formato de un objeto ReportedErrorEvent, copia sus campos en el objeto jsonPayload. Para obtener más información y un ejemplo, consulta Cómo registrar un error con el formato de un objeto ReportedErrorEvent.

  • Un jsonPayload que no incluye un campo message, stack_trace o exception, pero sí incluye un seguimiento de pila.

    Error Reporting busca seguimientos de pila en todos los campos de un objeto jsonPayload. Si se encuentra más de un seguimiento de pila, se selecciona uno. El algoritmo de selección garantiza 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 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 lo dejas sin configurar, Cloud Logging buscará 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 del jsonPayload contienen un seguimiento de pila. En esos casos, Error Reporting captura automáticamente el evento de error.

Recursos supervisados compatibles

Configura 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_job1
  • workflows.googleapis.com/Workflow
  • global1

1 textPayload no compatible

Ejemplos

En esta sección, se muestra cómo puedes asegurarte de que Error Reporting procese una entrada de registro cuando esta contenga un mensaje de texto o un seguimiento de pila.

Registra 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 deseas registrar un evento de error que es un mensaje de texto. Para ello, usa la siguiente estructura JSON para el campo jsonPayload del objeto 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 Error Reporting a 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 es necesario que especifiques el campo @type.

Registra un error con el formato de un objeto ReportedErrorEvent

Cuando tu evento de error se almacena en un objeto ReportedErrorEvent, usa 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úrate de completar el campo message con la información del error. Para obtener información sobre 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 ilustra cómo configurar el campo jsonPayload del objeto LogEntry para que se formatee 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

Puedes registrar un evento de error con el campo textPayload de un LogEntry para almacenar el mensaje de error, como un seguimiento de pila. 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 agrupada 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)"
    ...
}