Mettre en forme les erreurs dans les journaux

Ce document explique comment mettre en forme l'entrée de journal lorsque vous souhaitez utiliser Cloud Logging pour signaler des événements associés à des erreurs.

Vous pouvez signaler les événements d'erreur à votre projet Google Cloud en exécutant la méthode de l'API Cloud Logging write ou la méthode de l'API Error Reporting report. Lorsque vous signalez des événements d'erreur à l'aide de l'API Cloud Logging, le corps de la requête contient un objet LogEntry qui doit inclure une trace de la pile ou un objet ReportedErrorEvent.

Avant de commencer

  • Suivez les instructions de configuration correspondant à votre langage et à votre plate-forme.

  • Si vous avez besoin d'une authentification basée sur des clés API, vous devez utiliser l'API Error Reporting. Pour signaler un événement d'erreur à l'aide de l'API Error Reporting, exécutez la méthode report et mettez en forme le corps de la requête en tant qu'objet ReportedErrorEvent.

    Lorsque vous utilisez l'API Error Reporting, les entrées de journal contenant des messages d'erreur correctement formatés sont automatiquement générées et écrites dans Cloud Logging. Ces entrées de journal sont écrites dans un journal dont le logName est formaté comme suit:

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

    Les entrées de journal étant générées par des appels à report, des coûts d'ingestion dans Cloud Logging peuvent s'appliquer. Pour contrôler les journaux ingérés, consultez la section Filtres d'exclusion.

    Si vous signalez des événements associés à des erreurs à l'aide de l'API Error Reporting, le reste de ce document ne s'applique pas.

Exigences concernant le format LogEntry

Cette section explique comment mettre en forme un élément LogEntry afin qu'Error Reporting capture l'événement d'erreur contenu dans l'entrée de journal.

Enregistrer une trace de la pile

Pour consigner un événement d'erreur qui est une trace de pile, écrivez l'événement d'erreur de l'un des types suivants:

  • Un textPayload multiligne.
  • Un jsonPayload qui inclut un champ message, stack_trace ou exception.

    Vous pouvez spécifier plusieurs de ces champs. Si plusieurs de ces champs sont spécifiés, l'ordre d'évaluation est le suivant : stack_trace, puis exception, puis message.

    Si votre événement d'erreur est mis en forme en tant qu'objet ReportedErrorEvent, copiez ses champs dans jsonPayload. Pour en savoir plus et obtenir un exemple, consultez la section Consigner une erreur mise en forme en tant qu'objet ReportedErrorEvent.

  • Un jsonPayload qui n'inclut pas de champ message, stack_trace ni exception, mais qui inclut une trace de la pile.

    Error Reporting recherche les traces de la pile dans tous les champs d'un jsonPayload. Si plusieurs traces de pile sont détectées, une seule est sélectionnée. L'algorithme de sélection garantit un choix cohérent.

Enregistrer un SMS

Pour consigner un événement d'erreur sous forme de message texte, utilisez le format suivant pour jsonPayload:

    "jsonPayload": {
      "@type": "type.googleapis.com/google.devtools.clouderrorreporting.v1beta1.ReportedErrorEvent",
      "message": "Text message"
    },

Lorsque vous définissez le champ @type sur la valeur spécifiée, Error Reporting évalue toujours l'entrée de journal comme si tous les champs obligatoires étaient présents. Par conséquent, Error Reporting capture l'événement d'erreur.

Si vous définissez le champ @type sur une valeur différente ou ne le définissez pas, Cloud Logging recherche le champ intitulé serviceContext pour déterminer si la charge utile est un objet ReportedErrorEvent.

Vous n'avez pas besoin de définir le champ @type lorsque les champs message, stack_trace ou exception du jsonPayload contiennent une trace de la pile. Dans ce cas, Error Reporting capture automatiquement l'événement d'erreur.

Ressources surveillées compatibles

Définissez le champ resource de l'objet LogEntry sur l'un des types de ressources surveillées compatibles suivants:

  • 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 Champ textPayload non compatible

Examples

Cette section explique comment vous assurer qu'Error Reporting traite une entrée de journal lorsque celle-ci contient un message texte ou une trace de la pile.

Consigner un événement d'erreur sous forme de SMS

L'exemple suivant montre comment mettre en forme un objet LogEntry lorsque vous souhaitez consigner un événement d'erreur sous forme de message textuel. Utilisez la structure JSON suivante pour le champ 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"
  }
}

Comme le montre l'exemple, vous devez définir le champ @type sur la valeur qui oblige Error Reporting à regrouper l'entrée de journal. Pour en savoir plus, consultez Consigner un message.

Lorsque le champ message contient une trace de pile, l'entrée de journal est automatiquement regroupée. Vous n'avez donc pas besoin de spécifier le champ @type.

Consigner une erreur formatée en tant qu'objet ReportedErrorEvent

Lorsque votre événement d'erreur est stocké dans un objet ReportedErrorEvent, utilisez la structure JSON suivante pour le champ 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
    }
  }
}

Veillez à renseigner le champ message avec les informations d'erreur. Pour savoir comment stocker une trace de la pile dans le champ message d'un objet ReportedErrorEvent, consultez la page de référence de la méthode report.

L'exemple suivant montre comment définir le champ jsonPayload de LogEntry pour qu'il soit mis en forme en tant qu'objet ReportedErrorEvent. Comme le champ message contient une trace de la pile, l'événement d'erreur est regroupé par Error Reporting:

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

Consignez un événement d'erreur à l'aide du champ textPayload.

Vous pouvez enregistrer un événement d'erreur en utilisant le champ textPayload d'un LogEntry pour stocker les données d'erreur. Par exemple, la commande Google Cloud CLI suivante génère une entrée de journal dont le niveau de gravité est ERROR et dont le champ textPayload contient un événement d'erreur:

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)'

Le résultat de la commande précédente est une entrée de journal regroupée par 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)"
    ...
}