Formattare una voce di log per segnalare gli eventi di errore

Puoi formattare le voci di log di Cloud Logging in modo che Error Reporting acquisisca e raggruppi automaticamente gli errori dell'applicazione, aiutandoti a monitorare e diagnosticare i problemi nei tuoi servizi.

Quando scrivi voci di log utilizzando Cloud Logging, l'oggetto LogEntry deve contenere un'analisi dello stack o un oggetto ReportedErrorEvent formattato. Utilizza le sezioni seguenti per formattare i payload di testo e i campi JSON, come message, stack_trace e @type, in modo che Error Reporting analizzi e raggruppi correttamente gli eventi di errore.

Prima di iniziare

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

  • Se è richiesta 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, potresti incorrere in costi di importazione di Cloud Logging. Per controllare le voci di log importate, consulta Filtri di esclusione.

    Se segnali eventi di errore utilizzando l'API Error Reporting, il resto di questo documento non è applicabile.

Requisiti di formato di 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 ne viene specificato più di uno, l'ordine di valutazione è: stack_trace, quindi exception e infine message.

    Se il campo message viene valutato e non è vuoto, l' analisi dello stack viene acquisita solo quando il campo contiene un'analisi dello stack in uno dei formati dei linguaggi di programmazione supportati. L'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 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 le analisi dello stack in tutti i campi di un jsonPayload. Se viene trovata più di un'analisi dello stack, ne viene selezionata una. L'algoritmo di selezione garantisce una scelta coerente.

Registrare un messaggio di testo

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 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 un campo con etichetta serviceContext per determinare se il payload è un oggetto ReportedErrorEvent.

Non è necessario impostare il campo @type quando il campo message, stack_trace o exception di jsonPayload contiene 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 supportato

Esempi

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

Registrare un evento di errore che è un messaggio di testo

Per registrare un evento di errore che è un messaggio di testo, formatta l'oggetto LogEntry utilizzando la seguente struttura JSON per il campo 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"
  }
}

Come mostra l'esempio, devi impostare il campo @type sul valore che forza Error Reporting a 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, quindi non è necessario specificare il campo @type.

Registrare un errore formattato come oggetto ReportedErrorEvent

Quando l'evento di errore è archiviato in un ReportedErrorEvent oggetto, 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 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 in modo che venga formattato come oggetto ReportedErrorEvent. Poiché il campo message contiene un'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 archiviare il messaggio di errore, ad esempio un'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 da 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)"
    ...
}