Formattare una voce di log per segnalare gli eventi di errore

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 progetto Google Cloud 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 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 Reportingg. 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 nel seguente modo:

    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 quali voci di log vengono importate, 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 Error Reporting acquisisca l'evento di errore contenuto nella voce di log.

Registrare 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 vengono specificati più campi, l'ordine di valutazione è: stack_trace, poi exception e poi message.

    Se il campo del messaggio viene valutato e non è vuoto, lo analisi dello stack viene acquisito solo quando il campo contiene uno analisi dello stack in uno dei formati dei linguaggi di programmazione supportati. La analisi 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 ed un esempio, vedi 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 vengono trovate più analisi dello 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, Error Reporting valuta sempre la voce di log come se tutti i campi obbligatori fossero presenti. 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 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 supportato

Esempi

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

Registrare 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 Error Reporting a raggruppare la voce di log: per ulteriori informazioni, vedi Registrare un messaggio di testo.

Quando il campo message contiene una analisi dello stack, la voce di log viene raggruppata automaticamente, quindi non devi 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 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 analisi dello stack nel campo message di un oggetto ReportedErrorEvent, consulta la pagina di riferimento per il metodo report.

L'esempio seguente mostra come impostare il campo jsonPayload di LogEntry in modo che venga formattato come oggetto ReportedErrorEvent. Poiché il campo message contiene una analisi 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"
}

Registrare un evento di errore utilizzando il campo textPayload

Puoi registrare un evento di errore utilizzando il campo textPayload di un LogEntry per memorizzare il messaggio di errore, ad esempio una analisi dello stack. 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 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)"
    ...
}