Mettre en forme une entrée de journal pour signaler des événements d'erreur

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 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 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 formaté 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 entrées de journal ingérées, consultez 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 comme l'un des types suivants :

  • Champ 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 le champ de message est évalué et qu'il n'est pas vide, la trace de pile n'est capturée que si le champ contient une trace de pile dans l'un des formats de langage de programmation compatibles. La trace de pile n'est pas capturée par Error Reporting lorsqu'un format non compatible est utilisé.

    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 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 pile.

    Error Reporting recherche les traces de pile dans tous les champs d'un jsonPayload. Si plusieurs traces de pile sont trouvées, l'une d'elles 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 autre valeur ou si vous le laissez non défini, 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 de jsonPayload contiennent une trace de 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és 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

Exemples

Cette section explique comment vous assurer qu'Error Reporting traite une entrée de journal lorsqu'elle contient un message texte ou une trace de pile.

Consigner un événement d'erreur sous forme de 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 Error Reporting à grouper l'entrée de journal : Pour en savoir plus, consultez Enregistrer un message texte.

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 mise en forme 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
    }
  }
}

Assurez-vous de renseigner le champ message avec les informations sur l'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 groupé 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 le message d'erreur, tel qu'une trace de pile. 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)"
    ...
}