Errori di formato nei log

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

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

Prima di iniziare

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

  • Se richiedi l'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 il cui logName è formattato come segue:

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

    Poiché le voci di log vengono generate dalle chiamate a report, potrebbero esserti addebitati i costi di importazione di Cloud Logging. Per controllare quali log vengono importati, consulta la sezione Filtri di esclusione.

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

Requisiti per il formato LogEntry

Questa sezione descrive come formattare un elemento LogEntry in modo che Error Reporting 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 elemento jsonPayload che include un campo message, stack_trace o exception.

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

    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 elemento jsonPayload che non include un campo message, stack_trace o exception, ma include un'analisi dello stack.

    Error Reporting cerca in tutti i campi in un jsonPayload le analisi dello stack. Se vengono trovate più analisi dello stack, viene selezionata una sola analisi dello stack. L'algoritmo di selezione garantisce una scelta coerente.

Registra un SMS

Per registrare un evento di errore sotto forma di messaggio, 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, Error Reporting 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 non lo imposti, Cloud Logging cerca il campo con etichetta serviceContext per determinare se il payload è un oggetto ReportedErrorEvent.

Non è necessario impostare il campo @type se i campi message, stack_trace o exception di jsonPayload contengono un'analisi 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 supportata

Esempi

Questa sezione mostra come assicurarti che Error Reporting elabori una voce di log che contiene un messaggio di testo o un'analisi dello stack.

Registra un evento di errore sotto forma di 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 illustrato nell'esempio, devi impostare il campo @type sul valore che impone a Error Reporting di raggruppare la voce di log: Per ulteriori informazioni, consulta Registrare un messaggio di testo.

Quando il campo message contiene un'analisi dello stack, la voce di log viene raggruppata automaticamente in modo che non sia necessario specificare il campo @type.

Registra un errore formattato come oggetto ReportedErrorEvent

Quando l'evento di errore viene archiviato in un oggetto ReportedErrorEvent, utilizza la seguente struttura JSON per il campo jsonPayload dell'oggetto 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 archiviare un'analisi dello stack nel campo message di un oggetto ReportedErrorEvent, consulta la pagina di riferimento per il metodo report.

L'esempio seguente illustra come impostare il campo jsonPayload di LogEntry affinché venga formattato come oggetto ReportedErrorEvent. Poiché il campo message contiene un'analisi dello stack, l'evento di errore viene raggruppato in base a 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 LogEntry per archiviare i dati di errore. Ad esempio, il seguente comando Google Cloud CLI genera una voce di log con 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 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)"
    ...
}