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 d'erreur.

Vous pouvez signaler des événements associés à des erreurs à 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 associés à des erreurs à 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 applicables à votre langage et à votre plate-forme.

  • Si vous avez besoin d'une authentification basée sur une clé 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 de la méthode en tant qu'objet ReportedErrorEvent.

    Lorsque vous utilisez l'API Error Reporting, des entrées de journal avec 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 mis en forme comme suit:

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

    Étant donné que les entrées de journal sont générées par des appels à report, des coûts d'ingestion 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 d'erreur à 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 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 sous l'un des types suivants:

  • Un textPayload multiligne.

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

    Vous pouvez en spécifier plusieurs. Si vous en définissez plusieurs, l'ordre d'évaluation est le suivant : stack_trace, puis exception, puis message.

    Si le champ de message est évalué et s'il n'est pas vide, la trace de la pile n'est capturée que lorsque le champ contient une trace de la pile dans l'un des formats de langage de programmation compatibles. La trace de la pile n'est pas capturée par Error Reporting lorsqu'un format non compatible est utilisé.

    Si votre événement d'erreur est au format d'objet ReportedErrorEvent, copiez ses champs dans jsonPayload. Pour en savoir plus et obtenir un exemple, consultez la section Journaliser une erreur au format d'un objet ReportedErrorEvent.

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

    Error Reporting recherche des traces de 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 message

Pour consigner un événement d'erreur qui est un 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 si vous 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 pouvez vous assurer que le Error Reporting traite une entrée de journal lorsqu'elle contient un message textuel ou une trace de pile.

Enregistrer un événement d'erreur sous la forme d'un message texte

L'exemple suivant montre comment mettre en forme un objet LogEntry lorsque vous souhaitez consigner un événement d'erreur qui est un message texte. 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 force le Error Reporting à grouper l'entrée de journal : Pour en savoir plus, consultez la section Enregistrer un message texte.

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

Enregistrer une erreur au format d'un 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
    }
  }
}

Assurez-vous de renseigner le champ message avec les informations d'erreur. Pour savoir comment stocker une trace de 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 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"
}

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

Vous pouvez enregistrer un événement d'erreur à l'aide du 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)"
    ...
}