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

Vous pouvez mettre en forme les entrées de journal Cloud Logging afin qu'Error Reporting capture et regroupe automatiquement les erreurs de votre application. Vous pouvez ainsi surveiller et diagnostiquer les problèmes sur l'ensemble de vos services.

Lorsque vous écrivez des entrées de journal à l'aide de Cloud Logging, l'objet LogEntry doit contenir une trace de la pile ou un objet ReportedErrorEvent mis en forme. Utilisez les sections suivantes pour mettre en forme les charges utiles de texte et les champs JSON (tels que message, stack_trace et @type) afin qu'Error Reporting analyse et regroupe correctement vos événements d'erreur.

Avant de commencer

  • Suivez les instructions de configuration concernant 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, les entrées de journal contenant des messages d'erreur correctement mis en forme sont générées et écrites automatiquement 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, vous pouvez être soumis à des frais d'ingestion Cloud Logging. 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 de 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.

Consigner une trace de la pile

Pour consigner un événement d'erreur qui est une trace de la pile, écrivez l'événement d'erreur comme 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 le champ message est évalué et qu'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 mis en forme en tant qu'objet ReportedErrorEvent, copiez ses champs dans le 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 ou exception, mais qui inclut une trace de la pile.

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

Consigner un message texte

Pour consigner un événement d'erreur qui est un message texte, utilisez le format suivant pour le 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 un champ libellé serviceContext pour déterminer si la charge utile est un objet ReportedErrorEvent.

Vous n'avez pas besoin de définir le champ @type lorsque le champ message, stack_trace ou exception du jsonPayload contient 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és 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 textPayload non compatible

Exemples

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 qui est un message texte

Pour consigner un événement d'erreur qui est un message texte, mettez en forme l'objet LogEntry à l'aide de la structure JSON suivante pour le champ jsonPayload :

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

Consigner une erreur mise en forme en tant qu'objet ReportedErrorEvent

Lorsque votre événement d'erreur est stocké dans un ReportedErrorEvent objet, utilisez la structure JSON suivante pour le jsonPayload champ de le 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 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 du LogEntry pour qu'il soit mis en forme en tant qu'objet ReportedErrorEvent. Étant donné que 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"
}

Consigner 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 la 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)"
    ...
}