Errori di formattazione nei log

Questo documento spiega come formattare la voce di log quando vuoi utilizzare Cloud Logging per segnalare gli eventi di errore.

Puoi segnalare gli eventi di errore al tuo Google Cloud progetto eseguendo il metodo dell'API Cloud Logging write o il metodo dell'API Error Reporting report. Quando segnali eventi di errore utilizzando l'API Cloud Logging, il corpo della richiesta contiene un oggetto LogEntry che deve includere una traccia dello stack o un oggetto ReportedErrorEvent.

Prima di iniziare

  • Segui le istruzioni di configurazione per la tua lingua e la tua piattaforma.

  • Se hai bisogno di autenticazione basata su chiave API, devi utilizzare l'API Error Reporting. Per segnalare un evento di errore utilizzando l'API Error Reporting, esegui il metodo report e formatta il corpo della richiesta del metodo come oggetto ReportedErrorEvent.

    Quando utilizzi l'API Error Reporting, le voci di log con messaggi di errore formattati correttamente vengono generate e scritte automaticamente in Cloud Logging. Queste voci di log vengono scritte in un log logName il cui formato è il seguente:

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

    Poiché le voci di log vengono generate dalle chiamate a report, potresti incorrere in costi di importazione di Cloud Logging. Per controllare i log che vengono importati, consulta Filtri di esclusione.

    Se segnali gli eventi di errore utilizzando l'API Error Reporting, il resto di questo documento non si applica.

Requisiti di formato LogEntry

Questa sezione descrive come formattare un LogEntry in modo che la segnalazione di errori acquisisca l'evento di errore contenuto nella voce di log.

Registra un'analisi dello stack

Per registrare un evento di errore che è un'analisi dello stack, scrivi l'evento di errore come uno di questi tipi:

  • Un textPayload multiriga.

  • Un jsonPayload che include un campo message, stack_trace o exception.

    Puoi specificare più di uno di questi campi. Se viene specificato più di uno di questi campi, l'ordine di valutazione è:stack_trace, exception e message.

    Se il campo messaggio viene valutato e non è vuoto, la traccia di stack viene acquisita solo quando il campo contiene una traccia di stack in uno dei formati dei linguaggi di programmazione supportati. La traccia dello stack non viene acquisita da Error Reporting quando viene utilizzato un formato non supportato.

    Se l'evento di errore è formattato come oggetto ReportedErrorEvent, copia i relativi campi in jsonPayload. Per ulteriori informazioni e un esempio, consulta Registrare un errore formattato come oggetto ReportedErrorEvent.

  • Un jsonPayload che non include un campo message, stack_trace o exception, ma include un'analisi dello stack.

    Error Reporting cerca in tutti i campi di un jsonPayload le tracce dello stack. Se viene trovata più di una traccia di stack, ne viene selezionata una. L'algoritmo di selezione garantisce una scelta coerente.

Registrare un messaggio

Per registrare un evento di errore che è un messaggio di testo, utilizza il seguente formato per jsonPayload:

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

Quando imposti il campo @type sul valore specificato, la generazione di report sugli errori valuta sempre la voce di log come se fossero presenti tutti i campi obbligatori. Di conseguenza, Error Reporting acquisisce l'evento di errore.

Se imposti il campo @type su un valore diverso o lo lasci non impostato, Cloud Logging cerca il campo etichettato serviceContext per determinare se il payload è un oggetto ReportedErrorEvent.

Non è necessario impostare il campo @type quando i campi message, stack_trace o exception di jsonPayload contengono una traccia dello stack. In questi casi, Error Reporting acquisisce automaticamente l'evento di errore.

Risorse monitorate supportate

Imposta il campo resource dell'oggetto LogEntry su uno dei seguenti tipi di risorse monitorate supportati:

  • 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 supportato

Esempi

Questa sezione illustra come assicurarti che la segnalazione di errori elabori una voce di log quando questa contiene un messaggio di testo o una traccia dello stack.

Registra un evento di errore che è un messaggio di testo

L'esempio seguente mostra come formattare un oggetto LogEntry quando vuoi registrare un evento di errore che è un messaggio di testo. Utilizza la seguente struttura JSON per il campo jsonPayload di 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"
  }
}

Come mostrato nell'esempio, devi impostare il campo @type sul valore che forza la segnalazione degli errori a raggruppare la voce di log: Per ulteriori informazioni, consulta Registrare un messaggio.

Quando il campo message contiene una traccia dello stack, la voce di log viene raggruppata automaticamente, quindi non è necessario specificare il campo message.@type

Registra un errore formattato come oggetto ReportedErrorEvent

Quando l'evento di errore è archiviato in un oggetto ReportedErrorEvent, utilizza la seguente struttura JSON per il campo jsonPayload di 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
    }
  }
}

Assicurati di compilare il campo message con le informazioni sull'errore. Per scoprire come memorizzare una traccia dello stack nel campo message di un oggetto ReportedErrorEvent, consulta la pagina di riferimento del metodo report.

L'esempio seguente illustra come impostare il campo jsonPayload di LogEntry in modo che venga formattato come oggetto ReportedErrorEvent. Poiché il campo message contiene una traccia dello stack, l'evento di errore viene raggruppato da 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"
}

Registra un evento di errore utilizzando il campo textPayload

Puoi registrare un evento di errore utilizzando il campo textPayload di un LogEntry per memorizzare i dati dell'errore. Ad esempio, il seguente comando Google Cloud CLI genera una voce di log il cui livello di gravità è ERROR e il cui campo textPayload contiene un evento di errore:

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

Il risultato del comando precedente è una voce di log raggruppata per segnalazione errori:

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