Cómo formatear los errores en los registros

En esta página se explica el formato de entrada de registro necesario para usar Cloud Logging a fin de informar sobre eventos de errores.

Antes de comenzar

Si usas la API de Error Reporting, puedes informar sobre los eventos de errores de tu aplicación si los escribes en ReportedErrorEvent. Cuando lo haces, se generan entradas de registro con mensajes de error con el formato correcto en Cloud Logging. El logName resultante tiene el siguiente formato:

  projects/<PROJECT_ID>/clouderrorreporting.googleapis.com%2Freported_errors

Es posible que incurras en costos de transferencia de Cloud Logging con este método; para controlar estos costos, revisa las exclusiones de registros.

Si prefieres usar Cloud Logging para informar sobre eventos de errores, lee las siguientes secciones.

Requisitos de formato

Las entradas de registro en Cloud Logging que contienen seguimientos de pila o excepciones, o que tienen el formato ReportedErrorEvent, generan errores en Error Reporting.

Los datos de errores se deben registrar en el campo de unión LogEntry payload como uno de estos tipos:

  • Una línea múltiple textPayload
  • El campo message de jsonPayload

También debes seguir las instrucciones de configuración para tu lenguaje y plataforma. Cuando se registran datos de errores de App Engine, Compute Engine y Google Kubernetes Engine, el único requisito de formato es que la entrada de registro contenga el mensaje de excepción y el seguimiento de pila completos.

Para aprender a dar formato al mensaje de excepción y al seguimiento de pila, ve a la sección ReportedErrorEvent en la página de referencia report de Error Reporting.

Especifica @type

Si tu entrada de registro contiene el @type de type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent, Error Reporting evalúa la entrada del registro como si todos los campos obligatorios estuvieran presentes y captura el evento de error.

Representación JSON

Cuando envíes datos de errores con Cloud Logging, el ReportedErrorEvent que proporciones debe usar la siguiente estructura JSON:

    {
      "eventTime": string,
      "serviceContext": {
        "service": string,     // Required.
        "version": string
      },
      "message": string,       // Required. Should contain the full exception
                               // message, including the stack trace.
      "@type": string          // Optional.  Review "Specifying @type" section above.
      "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
        }
      }
    }

Tipos de recursos supervisados compatibles

Cuando se realiza el registro a través de la estructura LogEntry, el campo resource se debe establecer en uno de los siguientes tipos de recursos supervisados compatibles:

  • app_script_function
  • aws_ec2_instance
  • cloud_function
  • cloud_run_revision
  • consumed_api
  • container
  • dataflow_step
  • gae_app
  • gce_instance
  • k8s_container
  • ml_job1
  • global1

1 textPayload no compatible

Ejemplos de formato de entradas de registros

En los siguientes ejemplos, se ilustran entradas de registro que Error Reporting procesa correctamente si se registran en LogEntry.jsonPayload.

Esta entrada de registro está agrupada porque @type se especificó correctamente:

{...
  {
    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "An error message without stacktrace or exception"
    },
    "logName": "projects/test-project/logs/reported-error",
    "resource": {
      "labels": {
        "project_id": "test-project"
      },
      "type": "global"
    },
    "severity": "ERROR",
    "timestamp": "2019-06-27T13:43:26.375834551Z"
  }
}

El message de la carga útil de esta entrada de registro contiene un seguimiento de pila y una excepción, por lo que Error Reporting también lo agrupa:

{
      "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"
      }
    }

Para obtener detalles sobre los campos que se usan en una instancia de ReportedErrorEvent, consulta la documentación.