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'objetReportedErrorEvent
.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 champmessage
,stack_trace
ouexception
.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
, puisexception
, puismessage
.Si votre événement d'erreur est mis en forme en tant qu'objet
ReportedErrorEvent
, copiez ses champs dansjsonPayload
. Pour en savoir plus et obtenir un exemple, consultez la section Consigner une erreur mise en forme en tant qu'objetReportedErrorEvent
.Un
jsonPayload
qui n'inclut pas de champmessage
,stack_trace
niexception
, 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_job
1workflows.googleapis.com/Workflow
global
1
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)" ... }