Formatear una entrada de registro para informar de eventos de error

En este documento se explica cómo dar formato a la entrada de registro cuando quiera 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 objeto ReportedErrorEvent.

    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é entradas de registro se ingieren, consulta 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 campo message, stack_trace o exception.

    Puede 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 message.

    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 la pila cuando se usa un formato no admitido.

    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 Registrar un error con el formato de un objeto ReportedErrorEvent.

  • Un jsonPayload que no incluye los campos message, stack_trace ni exception, pero sí incluye un rastreo de pila.

    Informes de errores busca en todos los campos de un jsonPayload para rastrear la pila. Si se encuentra más de un seguimiento 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 le asigna ninguno, 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 rastreo 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_job1
  • workflows.googleapis.com/Workflow
  • global1

1 textPayload no compatible

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, debes definir el campo @type con el valor que obliga a Informes de errores a agrupar la entrada de registro: Para obtener más información, consulta 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

Cuando el evento de error se almacene en un objeto ReportedErrorEvent, utilice 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 rellenar el campo message con la información del error. Para saber cómo almacenar un rastreo 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 mediante el campo textPayload de un LogEntry para almacenar el mensaje de error, como un seguimiento de pila. 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)"
    ...
}