Logging strutturato

Questo documento illustra il concetto di logging strutturato e i metodi per aggiungere una struttura ai campi del payload voce di log. Quando il payload del log viene formattato come oggetto JSON e questo oggetto viene archiviato nel campo jsonPayload, la voce di log viene chiamata log strutturato. Per questi log, puoi creare query che cercano percorsi JSON specifici e puoi indicizzare campi specifici nel payload del log. Al contrario, quando il payload del log viene formattato come stringa e archiviato nel campo textPayload, la voce di log è non strutturata. Puoi cercare nel campo di testo, ma non puoi indicizzarne i contenuti.

Per creare voci di log strutturate, esegui una delle seguenti operazioni:

  • Chiama il metodo API entries.write e fornisci un LogEntry completamente formattato.
  • Utilizza il comando gcloud logging write.
  • Utilizza una libreria client di Cloud Logging che scrive log strutturati.
  • Utilizza il servizio BindPlane.

  • Utilizza un agente per scrivere i log:

    • Alcuni Google Cloud servizi contengono un agente di logging integrato che invia i dati scritti in stdout o stderr come log a Cloud Logging. Puoi utilizzare questo approccio per Google Cloud servizi come Google Kubernetes Engine, ambiente flessibile di App Engine e funzioni Cloud Run.

    • Per le macchine virtuali (VM) Compute Engine, puoi installare e configurare Ops Agent o l'agente Logging legacy, quindi utilizzare l'agente installato per inviare i log a Cloud Logging.

Per saperne di più su questi approcci, consulta le sezioni seguenti.

Scrivere i log utilizzando le librerie client o l'API

Puoi scrivere dati di log utilizzando le librerie client di Cloud Logging, che chiamano l'API Cloud Logging, o chiamando direttamente l'API Cloud Logging. Le librerie client possono semplificare la compilazione dei campi JSON speciali acquisendo automaticamente alcune informazioni e fornendo interfacce per popolare i campi in modo appropriato. Tuttavia, per un controllo completo sulla struttura dei payload, chiama direttamente l'API Cloud Logging e passa la struttura LogEntry completa all'API Cloud Logging.

Per saperne di più, consulta la documentazione di riferimento di entries.write.

Per esempi di codice, vedi Scrivere log strutturati.

Scrivere i log utilizzando gcloud CLI

Puoi scrivere dati di log utilizzando gcloud CLI. L'interfaccia supporta log non strutturati e log strutturati. Quando vuoi scrivere un log strutturato, fornisci al comando un oggetto JSON serializzato.

Per una guida rapida, vedi Scrivere voci di log ed eseguire query con Google Cloud CLI.

Per esempi di codice, consulta la documentazione di riferimento di gcloud logging write.

Scrivere i log utilizzando BindPlane

Puoi utilizzare il servizio BindPlane per inviare i log a Logging. Per questi log, i payload sono in formato JSON e sono strutturati in base al sistema di origine. Per informazioni su come trovare e visualizzare i log importati utilizzando BindPlane, consulta la Guida rapida di BindPlane .

Scrivere i log utilizzando un agente

Per ottenere i log dalle istanze Compute Engine, puoi utilizzare Ops Agent o l'agente Cloud Logging legacy. Entrambi gli agenti possono raccogliere metriche da applicazioni di terze parti e supportano il logging strutturato:

  • Ops Agent è l'agente consigliato per la raccolta dei dati di telemetria dalle istanze Compute Engine. Questo agente combina logging e metriche in un singolo agente, fornisce una configurazione basata su YAML e offre un logging a velocità effettiva elevata.

    Per informazioni su come configurare Ops Agent per supportare il logging strutturato o personalizzare il formato di un log strutturato, vedi Configurare Ops Agent.

  • L'agente Cloud Logging legacy raccoglie i log. Questo agente non raccoglie altre forme di telemetria.

La parte restante di questa sezione è specifica per l'agente Logging legacy.

Agente Logging: campi JSON speciali

Alcuni campi dell'oggetto JSON vengono riconosciuti come speciali dal l'agente Logging legacy ed estratti nella LogEntry struttura. Questi campi JSON speciali possono essere utilizzati per impostare i seguenti campi in LogEntry:

  • severity
  • spanId
  • labels definiti dall'utente
  • httpRequest

Poiché JSON è più preciso e versatile delle righe di testo, puoi utilizzare gli oggetti JSON per scrivere messaggi su più righe e aggiungere metadati.

Per creare voci di log strutturate per le tue applicazioni utilizzando il formato semplificato, consulta la tabella seguente, che elenca i campi e i relativi valori in JSON:

Campo di log JSON LogEntry campo Funzione dell'agente Cloud Logging Valore di esempio
severity severity L'agente Logging tenta di trovare una corrispondenza con una serie di stringhe di gravità comuni, inclusa la lista di LogSeverity riconosciute dall' API Logging. "severity":"ERROR"
message textPayload (o parte di jsonPayload) Il messaggio che viene visualizzato nella riga della voce di log in Esplora log. "message":"There was an error in the application."

Note: message is saved as textPayload if it is the only field remaining after the Logging agent moves the other special-purpose fields and detect_json wasn't enabled; otherwise message remains in jsonPayload. detect_json is not applicable to managed logging environments like Google Kubernetes Engine. Se la voce di log contiene una analisi dello stack di eccezioni, questa deve essere impostata in questo campo di log JSON message, in modo che la analisi dello stack di eccezioni possa essere analizzata e salvata in Error Reporting.
log (solo Google Kubernetes Engine legacy) textPayload Si applica solo a Google Kubernetes Engine legacy: se, dopo aver spostato i campi speciali, rimane solo un campo log, questo viene salvato come textPayload.
httpRequest httpRequest Un record strutturato nel formato del LogEntry HttpRequest campo. "httpRequest":{"requestMethod":"GET"}
campi relativi all'ora timestamp Per saperne di più, consulta Campi relativi all'ora. "time":"2025-10-12T07:20:50.52Z"
logging.googleapis.com/insertId insertId Per saperne di più, consulta insertId nella pagina LogEntry. "logging.googleapis.com/insertId":"42"
logging.googleapis.com/labels labels Il valore di questo campo deve essere un record strutturato. Per saperne di più, consulta labels nella pagina LogEntry. "logging.googleapis.com/labels": {"user_label_1":"value_1","user_label_2":"value_2"}
logging.googleapis.com/operation operation Il valore di questo campo viene utilizzato anche da Esplora log per raggruppare le voci di log correlate. Per saperne di più, consulta operation nella pagina LogEntry. "logging.googleapis.com/operation": {"id":"get_data","producer":"github.com/MyProject/MyApplication", "first":"true"}
logging.googleapis.com/sourceLocation sourceLocation Informazioni sulla posizione del codice sorgente associate alla voce di log, se presenti. Per saperne di più, consulta LogEntrySourceLocation nella pagina LogEntry. "logging.googleapis.com/sourceLocation": {"file":"get_data.py","line":"142","function":"getData"}
logging.googleapis.com/spanId spanId L'ID span nella traccia associata alla voce di log. Per saperne di più, consulta spanId nella pagina LogEntry. "logging.googleapis.com/spanId":"000000000000004a"
logging.googleapis.com/trace trace Nome della risorsa dell'eventuale traccia associata alla voce di log. Per saperne di più, consulta trace nella pagina LogEntry. "logging.googleapis.com/trace":"[TRACE_ID]"
"logging.googleapis.com/trace":"projects/my-projectid/traces/[TRACE_ID]"

Note: If not writing to stdout or stderr, format this field as [TRACE_ID] or use the legacy format projects/[PROJECT_ID]/traces/[TRACE_ID]. Entrambi i formati consentono a Esplora log e Trace Explorer di correlare i dati di log e di traccia. If autoformat_stackdriver_trace is true and [V] matches the format of the traceId field in the ResourceTrace object, then the LogEntry trace field has the value projects/[PROJECT_ID]/traces/[V].
logging.googleapis.com/trace_sampled traceSampled Il valore di questo campo deve essere true o false. Per saperne di più, consulta traceSampled nella pagina LogEntry. "logging.googleapis.com/trace_sampled": false

Per creare voci di log nel formato semplificato, crea una rappresentazione JSON della voce utilizzando i campi. Tutti i campi sono facoltativi.

Di seguito è riportato un esempio di voce di log JSON semplificata:

{
  "severity":"ERROR",
  "message":"There was an error in the application.",
  "httpRequest":{
    "requestMethod":"GET"
  },
  "time":"2020-10-12T07:20:50.52Z",
  "logging.googleapis.com/insertId":"42",
  "logging.googleapis.com/labels":{
    "user_label_1":"value_1",
    "user_label_2":"value_2"
  },
  "logging.googleapis.com/operation":{
    "id":"get_data",
    "producer":"github.com/MyProject/MyApplication",
    "first":"true"
  },
  "logging.googleapis.com/sourceLocation":{
    "file":"get_data.py",
    "line":"142",
    "function":"getData"
  },
  "logging.googleapis.com/spanId":"000000000000004a",
  "logging.googleapis.com/trace":"projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "logging.googleapis.com/trace_sampled":false
}

Di seguito è riportato un esempio della voce di log risultante:

{
  "insertId": "42",
  "jsonPayload": {
    "message": "There was an error in the application",
    "time": "2020-10-12T07:20:50.52Z"
  },
  "httpRequest": {
    "requestMethod": "GET"
  },
  "resource": {
    "type": "k8s_container",
    "labels": {
      "container_name": "hello-app",
      "pod_name": "helloworld-gke-6cfd6f4599-9wff8",
      "project_id": "stackdriver-sandbox-92334288",
      "namespace_name": "default",
      "location": "us-west4",
      "cluster_name": "helloworld-gke"
    }
  },
  "timestamp": "2020-10-12T07:20:50.52Z",
  "severity": "ERROR",
  "labels": {
    "user_label_2": "value_2",
    "user_label_1": "value_1"
  },
  "logName": "projects/stackdriver-sandbox-92334288/logs/stdout",
  "operation": {
    "id": "get_data",
    "producer": "github.com/MyProject/MyApplication",
    "first": true
  },
  "trace": "projects/my-projectid/traces/06796866738c859f2f19b7cfb3214824",
  "sourceLocation": {
    "file": "get_data.py",
    "line": "142",
    "function": "getData"
  },
  "receiveTimestamp": "2020-10-12T07:20:57.52Z",
  "spanId": "000000000000004a"
}

Agente Logging: configurazione

L'agente Logging legacy, google-fluentd, è un pacchetto di Fluentd, il raccoglitore di dati di log, specifico per Cloud Logging. L'agente Logging viene fornito con la configurazione Fluentd predefinita e utilizza i plug-in di input di Fluentd per estrarre i log degli eventi da origini esterne, ad esempio file su disco, o per analizzare i record di log in entrata.

Fluentd ha un elenco di parser supportati che estraggono i log e li convertono in payload strutturati (JSON).

Configurando un'origine log con format [PARSER_NAME], puoi basarti sui parser integrati forniti da Fluentd. Per informazioni sulla configurazione dell' agente Logging legacy, vedi Configurare l'agente Logging.

I seguenti esempi di codice mostrano la configurazione di Fluentd, il record di log di input e il payload strutturato di output, che fa parte di una voce di log di Cloud Logging:

  • Configurazione di Fluentd:

      <source>
    @type tail

    format syslog # This uses a predefined log format regex named
                  # `syslog`. See details at https://docs.fluentd.org/parser/syslog.

    path /var/log/syslog
    pos_file /var/lib/google-fluentd/pos/syslog.pos
    read_from_head true
    tag syslog
  </source>

  • Record di log (input):

      <6>Feb 28 12:00:00 192.168.0.1 fluentd[11111]: [error] Syslog test

  • Payload strutturato (output):

      jsonPayload: {
      "pri": "6",
      "host": "192.168.0.1",
      "ident": "fluentd",
      "pid": "11111",
      "message": "[error] Syslog test"
  }

Per saperne di più sul funzionamento del parser syslog, consulta la documentazione dettagliata di Fluentd.

Agente Logging: parser standard attivati per impostazione predefinita

La tabella seguente include i parser standard inclusi nell'agente se abiliti il logging strutturato:

Nome del parser File di configurazione
syslog /etc/google-fluentd/config.d/syslog.conf
nginx /etc/google-fluentd/config.d/nginx.conf
apache2 /etc/google-fluentd/config.d/apache.conf
apache_error /etc/google-fluentd/config.d/apache.conf

Per istruzioni su come abilitare il logging strutturato durante l'installazione dell' agente Logging legacy, consulta la sezione Installazione.

Agente Logging: installazione

Per abilitare il logging strutturato, devi modificare la configurazione predefinita dell'agente Logging legacy durante l'installazione o la reinstallazione. L'abilitazione del logging strutturato sostituisce i file di configurazione elencati in precedenza, ma non modifica il funzionamento dell'agente stesso.

Quando abiliti il logging strutturato, i log elencati vengono convertiti in voci di log con formati diversi da quelli precedenti all'abilitazione dei log strutturati. Se i log vengono indirizzati a destinazioni esterne a Logging, la modifica potrebbe influire su tutte le applicazioni di post-elaborazione. Ad esempio, se indirizzi i log a BigQuery, BigQuery rifiuta le nuove voci di log per il resto della giornata perché hanno uno schema errato.

Per istruzioni sull'installazione dell'agente Logging legacy e sull'abilitazione del logging strutturato, consulta Installare l'agente Logging agent.

Puoi trovare i file di configurazione dell'agente Logging legacy in /etc/google-fluentd/config.d/, che ora dovrebbero includere i parser standard attivati per impostazione predefinita.

Agente Logging: configurare il formato dei log di accesso di Apache

Per impostazione predefinita, l'agente Logging legacy archivia i dati dei log di accesso di Apache nel campo jsonPayload. Ad esempio:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "user"   : "some-user",
    "method" : "GET",
    "code"   : 200,
    "size"   : 777,
    "host"   : "192.168.0.1",
    "path"   : "/some-path",
    "referer": "some-referer",
    "agent"  : "Opera/12.0"
  },
  ...
}

In alternativa, puoi configurare l'agente Logging legacy in modo che estragga determinati campi nel campo httpRequest. Ad esempio:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user"
  },
  ...
}

La configurazione del campo httpRequest, come mostrato nell'esempio precedente, facilita la tracciabilità: la Google Cloud console presenta tutti i log per una determinata richiesta HTTP in una gerarchia padre-figlio.

Per configurare questa estrazione, aggiungi quanto segue alla fine di /etc/google-fluentd/config.d/apache.conf:

<filter apache-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "serverIp" => record['host'],
    "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, host, referer
</filter>

Per maggiori dettagli su come configurare le voci di log, vedi Modificare i record di log.

Agente Logging: configurare il formato dei log di accesso di nginx

Per impostazione predefinita, l'agente Logging legacy archivia i dati dei log di accesso di nginx nel campo jsonPayload. Ad esempio:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": ...,
  "jsonPayload": {
    "remote":"127.0.0.1",
    "host":"192.168.0.1",
    "user":"some-user",
    "method":"GET",
    "path":"/some-path",
    "code":"200",
    "size":"777",
    "referrer":"some-referrer",
    "agent":"Opera/12.0",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

In alternativa, puoi configurare l'agente Logging legacy in modo che estragga determinati campi nel campo httpRequest. Ad esempio:

{
  "logName": ...,
  "resource": ...,
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "/some-path",
    "requestSize": "777",
    "status": "200",
    "userAgent": "Opera/12.0",
    "remoteIp": "127.0.0.1",
    "serverIp": "192.168.0.1",
    "referrer":"some-referrer",
  },
  "jsonPayload": {
    "user":"some-user",
    "http_x_forwarded_for":"192.168.3.3"
  },
  ...
}

La configurazione del campo httpRequest, come mostrato nell'esempio precedente, facilita la tracciabilità: la Google Cloud console presenta tutti i log per una determinata richiesta HTTP in una gerarchia padre-figlio.

Per configurare questa estrazione, aggiungi quanto segue alla fine di /etc/google-fluentd/config.d/nginx.conf:

<filter nginx-access>
  @type record_transformer
  enable_ruby true
  <record>
    httpRequest ${ {"requestMethod" => record['method'], "requestUrl" => record['path'], "requestSize" => record['size'], "status" => record['code'], "userAgent" => record['agent'], "remoteIp" => record['remote'], "serverIp" => record['host'], "referer" => record['referer']} }
  </record>
  remove_keys method, path, size, code, agent, remote, host, referer
</filter>

Per maggiori dettagli su come configurare le voci di log, vedi Modificare i record di log.

Scrivere il tuo parser

Se i log non sono supportati dai parser standard, puoi scrivere il tuo parser. I parser sono costituiti da un'espressione regolare utilizzata per trovare corrispondenze con i record di log e applicare etichette alle parti.

I seguenti esempi di codice mostrano una riga di log nel record di log, una configurazione con un'espressione regolare che indica il formato della riga di log e la voce di log archiviata:

  • Una riga di log nel record di log:

    REPAIR CAR $500

  • Una configurazione con un'espressione regolare che indica il formato della riga di log:

    $ sudo vim /etc/google-fluentd/config.d/test-structured-log.conf
$ cat /etc/google-fluentd/config.d/test-structured-log.conf
<source>
  @type tail

  # Format indicates the log should be translated from text to
  # structured (JSON) with three fields, "action", "thing" and "cost",
  # using the following regex:
  format /(?<action>\w+) (?<thing>\w+) \$(?<cost>\d+)/
  # The path of the log file.
  path /tmp/test-structured-log.log
  # The path of the position file that records where in the log file
  # we have processed already. This is useful when the agent
  # restarts.
  pos_file /var/lib/google-fluentd/pos/test-structured-log.pos
  read_from_head true
  # The log tag for this log input.
  tag structured-log
</source>

  • La voce di log risultante:

    {
insertId:  "eps2n7g1hq99qp"
jsonPayload: {
  "action": "REPAIR"
  "thing": "CAR"
  "cost": "500"
}
labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
}
logName:  "projects/my-sample-project-12345/logs/structured-log"
receiveTimestamp:  "2023-03-21T01:47:11.475065313Z"
resource: {
  labels: {
    instance_id:  "3914079432219560274"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
}
timestamp:  "2023-03-21T01:47:05.051902169Z"
}

Risoluzione dei problemi

Per risolvere i problemi comuni riscontrati durante l'installazione o l'interazione con l' agente Logging legacy, vedi Risolvere i problemi dell'agienza.

Passaggi successivi