Configurazione dell'agente Logging

La personalizzazione della configurazione dell'agente Cloud Logging consente di trasmettere in streaming a Logging log aggiuntivi da file e applicazioni di terze parti sulle istanze di macchine virtuali (VM). Poiché l'agente Logging include una configurazione predefinita che raccoglie i log di sistema e delle applicazioni comuni, devi modificare la configurazione solo se vuoi personalizzare la raccolta dei log o esaminare il modo in cui l'agente elabora i record di log.

Configurazione predefinita

L'agente Logging google-fluentd è una versione modificata del raccoglitore di dati di log fluentd. L'agente Logging viene fornito con una configurazione predefinita; nella maggior parte dei casi comuni, non è necessaria alcuna configurazione aggiuntiva.

Nella configurazione predefinita, l'agente Logging trasmette i log, come inclusi nell'elenco dei log predefiniti, a Cloud Logging. Puoi configurare l'agente per lo streaming di log aggiuntivi. Per maggiori dettagli, consulta la sezione Personalizzazione della configurazione dell'agente Logging in questa pagina.

Come funziona l'agente Logging.

L'agente Logging utilizza i plug-in di input fluentd per recuperare ed estrarre i log eventi da origini esterne, ad esempio file su disco, o per analizzare i record di log in entrata. I plug-in di input sono integrati nell'agente o possono essere installati separatamente come gemme Ruby; consulta l'elenco dei plug-in integrati.

L'agente legge i record di log archiviati nei file di log nell'istanza VM utilizzando il plug-in in_tail integrato di fluentd. Ogni record di log viene convertito in una struttura di voce di log per Cloud Logging. I contenuti di ogni record di log vengono registrati principalmente nel payload delle voci di log, ma le voci di log contengono anche elementi standard come un timestamp e la gravità. L'agente Logging richiede che ogni record di log sia contrassegnato con un tag in formato stringa; tutte le query e i plug-in di output corrispondono a un insieme specifico di tag. Il nome del log di solito segue il formato projects/[PROJECT_ID]/logs/[TAG]. Ad esempio, questo nome di log include il tag structured-log:

projects/my-sample-project-12345/logs/structured-log

Il plug-in di output trasforma ogni messaggio strutturato internalizzato in una voce di log in Cloud Logging. Il payload diventa il payload di testo o JSON.

Le sezioni seguenti di questa pagina descrivono in dettaglio la configurazione predefinita.

Definizioni di configurazione predefinite

Le sezioni seguenti descrivono le definizioni di configurazione predefinite per syslog, il plug-in di input forward, le configurazioni di input per i log delle applicazioni di terze parti, come quelli nell'elenco dei log predefiniti, e il plug-in di output Google Cloud fluentd.

Posizione del file di configurazione principale

  • Linux: /etc/google-fluentd/google-fluentd.conf

    Questo file di configurazione principale importa anche tutti i file di configurazione dalla cartella /etc/google-fluentd/config.d.

  • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

    Se utilizzi un agente Logging precedente alla versione 1.5, la posizione è: C:\GoogleStackdriverLoggingAgent\fluent.conf

Configurazione Syslog

  • Posizioni dei file di configurazione: /etc/google-fluentd/config.d/syslog.conf

  • Descrizione: questo file include la configurazione per specificare syslog come input di log.

  • Esamina il repository di configurazione.

Nome della configurazione Tipo Predefinito Descrizione
format string /^(?<message>(?<time>[^ ]*\s*[^ ]* [^ ]*) .*)$/ Il formato del syslog.
path string /var/log/syslog Il percorso del file syslog.
pos_file string /var/lib/google-fluentd/pos/syslog.pos Il percorso del file di posizione per questo input di log. fluentd registra la posizione dell'ultima lettura in questo file. Consulta la documentazione dettagliata di fluentd.
read_from_head bool true Indica se iniziare a leggere i log dall'inizio del file anziché dalla fine. Consulta la documentazione dettagliata di fluentd.
tag string syslog Il tag di log per questo input di log.

Configurazione del plug-in di input in_forward

  • Posizioni dei file di configurazione: /etc/google-fluentd/config.d/forward.conf

  • Descrizione: questo file include la configurazione per il plug-in di input in_forward fluentd. Il plug-in di input in_forward consente di passare i log utilizzando un socket TCP.

  • Consulta la documentazione dettagliata di fluentd per questo plug-in e il repository di configurazione.

Nome della configurazione Tipo Predefinito Descrizione
port int 24224 La porta da monitorare.
bind string 127.0.0.1 L'indirizzo di associazione da monitorare. Per impostazione predefinita, sono accettate solo le connessioni da localhost. Per aprirla, questa configurazione deve essere modificata in 0.0.0.0.

Configurazione dell'input dei log delle applicazioni di terze parti

  • Posizioni dei file di configurazione: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf

  • Descrizione: questa directory include i file di configurazione per specificare i file di log delle applicazioni di terze parti come input di log. Ogni file, ad eccezione di syslog.conf e forward.conf, rappresenta un'applicazione (ad esempio, apache.conf per l'applicazione Apache).

  • Esamina il repository di configurazione.

Nome della configurazione Tipo Predefinito Descrizione
format1 string Varia in base all'applicazione Il formato del log. Consulta la documentazione dettagliata di fluentd.
path string Varia in base all'applicazione Il percorso dei file di log. È possibile specificare più percorsi, separati da ",". È possibile includere il carattere jolly * e i formati strftime per aggiungere o rimuovere dinamicamente i file monitorati. Consulta la documentazione dettagliata di fluentd.
pos_file string Varia in base all'applicazione Il percorso del file di posizione per questo input di log. fluentd registra la posizione dell'ultima lettura in questo file. Consulta la documentazione dettagliata di fluentd.
read_from_head bool true Indica se iniziare a leggere i log dall'inizio del file anziché dalla fine. Consulta la documentazione dettagliata di fluentd.
tag string Varia; il nome dell'applicazione. Il tag di log per questo input di log.

1 Se utilizzi la sezione <parse>, specifica il formato del log utilizzando @type.

Configurazione del plug-in di outputGoogle Cloud fluentd

  • Posizioni dei file di configurazione:

    • Linux: /etc/google-fluentd/google-fluentd.conf

    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Se utilizzi un agente Logging precedente alla versione 1.5, la posizione è: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Descrizione: questo file include opzioni di configurazione per controllare il comportamento del plug-in di outputGoogle Cloud fluentd.

  • Vai al repository di configurazione.

Nome della configurazione Tipo Predefinito Descrizione
buffer_chunk_limit string 512KB Man mano che i record di log arrivano, quelli che non possono essere scritti nei componenti downstream abbastanza velocemente vengono inseriti in una coda di blocchi. Questa configurazione imposta il limite di dimensioni di ogni chunk. Per impostazione predefinita, il limite di blocchi è impostato in modo prudente per evitare di superare la dimensione consigliata di 5 MB per richiesta di scrittura nell'API Logging. Le voci di log nella richiesta API possono essere da 5 a 8 volte più grandi delle dimensioni del log originale con tutti i metadati aggiuntivi allegati. Un blocco del buffer viene svuotato se viene soddisfatta una delle due condizioni:
1. flush_interval.
2. La dimensione del buffer raggiunge buffer_chunk_limit.
flush_interval string 5s Man mano che i record di log arrivano, quelli che non possono essere scritti nei componenti downstream abbastanza velocemente vengono inseriti in una coda di blocchi. La configurazione imposta il tempo che deve trascorrere prima che un blocco del buffer venga svuotato. Un blocco del buffer viene svuotato se viene soddisfatta una delle due condizioni:
1. flush_interval.
2. La dimensione del buffer raggiunge buffer_chunk_limit.
disable_retry_limit bool false Impone un limite al numero di nuovi tentativi di svuotamento non riuscito dei blocchi del buffer. Esamina le specifiche dettagliate in retry_limit, retry_wait e max_retry_wait.
retry_limit int 3 Quando non è possibile eseguire il flush di un blocco del buffer, per impostazione predefinita fluentd riprova in un secondo momento. Questa configurazione imposta il numero di nuovi tentativi da eseguire prima di eliminare un blocco di buffer problematico.
retry_wait int 10s Quando non è possibile eseguire il flush di un blocco del buffer, per impostazione predefinita fluentd riprova in un secondo momento. Questa configurazione imposta l'intervallo di attesa in secondi prima del primo nuovo tentativo. L'intervallo di attesa raddoppia a ogni tentativo successivo (20 s, 40 s e così via) fino a raggiungere retry_limit o max_retry_wait.
max_retry_wait int 300 Quando non è possibile eseguire il flush di un blocco del buffer, per impostazione predefinita fluentd riprova in un secondo momento. L'intervallo di attesa raddoppia a ogni nuovo tentativo successivo (20 s, 40 s…). Questa configurazione imposta l'intervallo di attesa massimo in secondi. Se l'intervallo di attesa raggiunge questo limite, il raddoppio si interrompe.
num_threads int 8 Il numero di flussi di log simultanei che possono essere elaborati dal plug-in di output.
use_grpc bool true Indica se utilizzare gRPC anziché REST/JSON per comunicare con l'API Logging. Con gRPC abilitato, l'utilizzo della CPU è in genere inferiore.
grpc_compression_algorithm enum none Se utilizzi gRPC, imposta lo schema di compressione da utilizzare. Può essere none o gzip.
partial_success bool true Indica se supportare il successo parziale per l'importazione dei log. Se true, le voci di log non valide in un set completo vengono ignorate e le voci di log valide vengono importate correttamente nell'API Logging. Se false, l'intero set verrebbe ignorato se contenesse voci di log non valide.
enable_monitoring bool true Se impostato su true, l'agente Logging esporta la telemetria interna. Per maggiori dettagli, consulta Telemetria dei plug-in di output.
monitoring_type string opencensus Il tipo di monitoraggio. Le opzioni supportate sono opencensus e prometheus. Per maggiori dettagli, consulta Telemetria dei plug-in di output.
autoformat_stackdriver_trace bool true Se impostata su true, la traccia viene riformattata se il valore del campo del payload strutturato logging.googleapis.com/trace corrisponde al formato ResourceTrace traceId. I dettagli della formattazione automatica sono disponibili nella sezione Campi speciali nei payload strutturati di questa pagina.

Configurazione del monitoraggio

Questa sezione descrive la configurazione di Cloud Monitoring.

Telemetria del plug-in di output

L'opzione enable_monitoring controlla se il plug-in di output Google Cloud fluentd raccoglie la propria telemetria interna. Se impostato su true, l'agente Logging tiene traccia del numero di voci di log di cui è stato richiesto l'invio a Cloud Logging e del numero effettivo di voci di log importate correttamente da Cloud Logging. Se impostato su false, il plug-in di output non raccoglie metriche.

L'opzione monitoring_type controlla il modo in cui questa telemetria viene esposta dall'agente. Di seguito è riportato l'elenco delle metriche.

Se impostato su prometheus, l'agente Logging espone le metriche in formato Prometheus sull'endpoint Prometheus (localhost:24231/metrics per impostazione predefinita; per maggiori dettagli sulla personalizzazione, consulta la configurazione dei plug-in prometheus e prometheus_monitor). Nelle VM di Compute Engine, affinché queste metriche vengano scritte nell'API Monitoring, deve essere installato e in esecuzione anche l'agente Monitoring.

Se impostato su opencensus (valore predefinito dalla v1.6.25), l'agente Logging scrive direttamente le proprie metriche di integrità nell'API Monitoring. Ciò richiede che il ruolo roles/monitoring.metricWriter venga concesso al service account predefinito di Compute Engine, anche se l'agente Monitoring non è installato.

Le seguenti metriche vengono scritte nell'API Monitoring sia dall'agente Monitoring sia dall'agente Logging in modalità opencensus:

  • agent.googleapis.com/agent/uptime con un'etichetta version: uptime dell'agente Logging.
  • agent.googleapis.com/agent/log_entry_count con un'etichetta response_code: conteggio delle voci di log scritte dall'agente Logging.
  • agent.googleapis.com/agent/log_entry_retry_count con un'etichetta response_code: conteggio delle voci di log scritte dall'agente Logging.
  • agent.googleapis.com/agent/request_count con un'etichetta response_code: conteggio delle richieste API dall'agente Logging.

Queste metriche sono descritte in maggiore dettaglio nella pagina Metriche dell'agente.

Inoltre, le seguenti metriche Prometheus vengono esposte dal plug-in di output in modalità prometheus:

  • uptime con un'etichetta version: uptime dell'agente Logging.
  • stackdriver_successful_requests_count con etichette grpc e code: il numero di richieste riuscite all'API Logging.
  • stackdriver_failed_requests_count con etichette grpc e code: il numero di richieste non riuscite all'API Logging, suddivise per codice di errore.
  • stackdriver_ingested_entries_count con etichette grpc e code: il numero di voci di log importate dall'API Logging.
  • stackdriver_dropped_entries_count con etichette grpc e code: il numero di voci di log rifiutate dall'API Logging.
  • stackdriver_retried_entries_count con etichette grpc e code: il numero di voci di log che non sono state importate dal plug-in di output Google Cloud fluentd a causa di un errore temporaneo e per le quali è stato eseguito un nuovo tentativo.

Configurazione dei plug-in prometheus e prometheus_monitor

  • Posizioni dei file di configurazione: /etc/google-fluentd/google-fluentd.conf

  • Descrizione: questo file include opzioni di configurazione per controllare il comportamento dei plug-in prometheus e prometheus_monitor. Il plug-in prometheus_monitor monitora l'infrastruttura di base di Fluentd. Il plug-in prometheus espone le metriche, incluse quelle del plug-in prometheus_monitor e quelle del plug-in google_cloud, utilizzando una porta locale in formato Prometheus. Per saperne di più, consulta Monitoraggio di Prometheus.

  • Vai al repository di configurazione.

Per il monitoraggio di Fluentd, il server di metriche HTTP Prometheus integrato è abilitato per impostazione predefinita. Puoi rimuovere la seguente sezione dalla configurazione per impedire l'avvio di questo endpoint:

# Prometheus monitoring.
<source>
  @type prometheus
  port 24231
</source>
<source>
  @type prometheus_monitor
</source>

Elaborazione dei payload

La maggior parte dei log supportati nella configurazione predefinita dell'agente Logging proviene da file di log e viene importata come payload non strutturati (testo) nelle voci di log.

L'unica eccezione è che il plug-in di input in_forward, anch'esso abilitato per impostazione predefinita, accetta solo log strutturati e li importa come payload strutturati (JSON) nelle voci di log. Per maggiori dettagli, leggi Flusso di record di log strutturati (JSON) utilizzando il plug-in in_forward in questa pagina.

Quando la riga di log è un oggetto JSON serializzato e l'opzione detect_json è abilitata, il plug-in di output trasforma la voce di log in un payload strutturato (JSON). Questa opzione è abilitata per impostazione predefinita nelle istanze VM in esecuzione nell'ambiente flessibile di App Engine. Questa opzione non è attivata per impostazione predefinita nelle istanze VM in esecuzione nell'ambiente standard App Engine. Qualsiasi JSON analizzato con l'opzione detect_json abilitata viene sempre importato come jsonPayload.

Puoi personalizzare la configurazione dell'agente per supportare l'importazione di log strutturati da risorse aggiuntive. Per maggiori dettagli, consulta Streaming di record di log strutturati (JSON) in Cloud Logging.

Il payload dei record di log trasmessi in streaming da un agente Logging configurato in modo personalizzato può essere un singolo messaggio di testo non strutturato (textPayload) o un messaggio JSON strutturato (jsonPayload).

Campi speciali nei payload strutturati

Quando l'agente Logging riceve un record di log strutturato, sposta qualsiasi chiave che corrisponde alla tabella seguente nel campo corrispondente dell'oggetto LogEntry. In caso contrario, la chiave diventa parte del campo LogEntry.jsonPayload. Questo comportamento ti consente di impostare campi specifici nell'oggetto LogEntry, che è ciò che viene scritto nell'API Logging. Ad esempio, se il record di log strutturato contiene una chiave severity, l'agente Logging compila il campo LogEntry.severity.

Campo di log JSON LogEntry field 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, tra cui l'elenco di stringhe LogSeverity riconosciute dall'API Logging. "severity":"ERROR"
message textPayload (o parte di jsonPayload) Il messaggio visualizzato nella riga della voce di log in Esplora log. "message":"There was an error in the application."

Nota: message viene salvato come textPayload se è l'unico campo rimanente dopo che l'agente Logging ha spostato gli altri campi per scopi speciali e detect_json non è stato abilitato; in caso contrario, message rimane in jsonPayload. detect_json non è applicabile agli ambienti di logging gestiti come Google Kubernetes Engine. Se la voce di log contiene un'analisi dello stack delle eccezioni, questa deve essere impostata in questo campo di log JSON message, in modo che l'analisi dello stack delle eccezioni possa essere analizzata e salvata in Error Reporting.
log (solo Google Kubernetes Engine legacy) textPayload Si applica solo alla versione precedente di Google Kubernetes Engine: se, dopo aver spostato i campi per scopi speciali, rimane solo un campo log, questo campo viene salvato come textPayload.
httpRequest httpRequest Un record strutturato nel formato del campo HttpRequest di LogEntry. "httpRequest":{"requestMethod":"GET"}
campi relativi al tempo timestamp Per saperne di più, consulta Campi relativi al tempo. "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 di 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]"

Nota: se non scrivi in stdout o stderr, formatta questo campo come [TRACE_ID] o utilizza il formato legacy projects/[PROJECT_ID]/traces/[TRACE_ID]. Entrambi i formati consentono a Esplora log ed Esplora tracce di correlare i dati di log e traccia. Se autoformat_stackdriver_trace è true e [V] corrisponde al formato del campo traceId nell'oggetto ResourceTrace, il campo LogEntry trace ha il valore 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

Campi relativi al tempo

In generale, le informazioni relative al tempo di una voce di log vengono archiviate nel campo timestamp dell'oggetto LogEntry:

{
insertId: "1ad8d08f-6529-47ea-832e-467f869a2da4"
...
resource: {2}
timestamp: "2023-10-30T16:33:15.505196Z"
}

Quando l'origine di una voce di log sono dati strutturati, l'agente Logging utilizza le seguenti regole per cercare nei campi della voce jsonPayload informazioni relative al tempo:

  1. Cerca un campo timestamp che sia un oggetto JSON che include i campi seconds e nanos, che rappresentano, rispettivamente, un numero di secondi con segno dall'epoca UTC e un numero non negativo di secondi frazionari:

    jsonPayload: {
  ...
  "timestamp": {
    "seconds": CURRENT_SECONDS,
    "nanos": CURRENT_NANOS
  }
}

  2. Se la ricerca precedente non va a buon fine, cerca una coppia di campi timestampSeconds e timestampNanos:

    jsonPayload: {
  ...
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS
}

  3. Se la ricerca precedente non va a buon fine, cerca un campo time che sia una stringa in formato RFC 3339:

    jsonPayload: {
  ...
  "time": CURRENT_TIME_RFC3339
}

Quando vengono trovate informazioni relative al tempo, l'agente Logging le utilizza per impostare il valore di LogEntry.timestamp e non le copia dal record strutturato nell'oggetto LogEntry.jsonPayload.

I campi relativi al tempo che non vengono utilizzati per impostare il valore del campo LogEntry.timestamp vengono copiati dal record strutturato nell'oggetto LogEntry.jsonPayload. Ad esempio, se il record strutturato contiene un oggetto JSON timestamp e un campo time, i dati nell'oggetto JSON timestamp vengono utilizzati per impostare il campo LogEntry.timestamp. L'oggetto LogEntry.jsonPayload contiene un campo time, perché questo campo non è stato utilizzato per impostare il valore LogEntry.timestamp.

Personalizzazione della configurazione dell'agente

Oltre all'elenco dei log predefiniti che l'agente Logging trasmette per impostazione predefinita, puoi personalizzare l'agente Logging in modo che invii log aggiuntivi a Logging o modificare le impostazioni dell'agente aggiungendo configurazioni di input.

Le definizioni di configurazione in queste sezioni si applicano solo al plug-in di output fluent-plugin-google-cloud e specificano il modo in cui i log vengono trasformati e importati in Cloud Logging.

  • Posizioni dei file di configurazione principali:

    • Linux: /etc/google-fluentd/google-fluentd.conf

    • Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

      Se utilizzi un agente Logging precedente alla versione 1.5, la posizione è: C:\GoogleStackdriverLoggingAgent\fluent.conf

  • Descrizione: questo file include opzioni di configurazione per controllare il comportamento del plug-in di output fluent-plugin-google-cloud.

  • Esamina il repository di configurazione.

Log in streaming da input aggiuntivi

Puoi personalizzare l'agente Logging per inviare log aggiuntivi a Logging aggiungendo configurazioni di input.

Streaming di log non strutturati (testo) utilizzando file di log

  1. Dal prompt dei comandi di Linux, crea un file di log:

    touch /tmp/test-unstructured-log.log

  2. Crea un nuovo file di configurazione denominato test-unstructured-log.conf nella directory di configurazione aggiuntiva /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-unstructured-log.conf <<EOF
<source>
    @type tail
    <parse>
        # 'none' indicates the log is unstructured (text).
        @type none
    </parse>
    # The path of the log file.
    path /tmp/test-unstructured-log.log
    # The path of the position file that records the position in the log
    # file that has already been processed. This is useful when the agent
    # restarts.
    pos_file /var/lib/google-fluentd/pos/test-unstructured-log.pos
    read_from_head true
    # The log tag for this log input.
    tag unstructured-log
</source>
EOF

    Un'alternativa alla creazione di un nuovo file è aggiungere le informazioni di configurazione a un file di configurazione esistente.

  3. Riavvia l'agente per applicare le modifiche alla configurazione:

    sudo service google-fluentd restart

  4. Genera un record di log nel file di log:

    echo 'This is a log from the log file at test-unstructured-log.log' >> /tmp/test-unstructured-log.log

  5. Controlla Esplora log per visualizzare la voce di log importata:

    {
  insertId:  "eps2n7g1hq99qp"
  labels: {
  compute.googleapis.com/resource_name:  "add-unstructured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/unstructured-log"
  receiveTimestamp:  "2018-03-21T01:47:11.475065313Z"
  resource: {
  labels: {
    instance_id:  "3914079432219560274"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
  }
  textPayload:  "This is a log from the log file at test-unstructured-log.log"
  timestamp:  "2018-03-21T01:47:05.051902169Z"
}

Streaming di log strutturati (JSON) utilizzando file di log

Puoi configurare l'agente Logging in modo che richieda che ogni voce di log per determinati input di log sia strutturata. Puoi anche personalizzare l'agente Logging per importare contenuti in formato JSON da un file di log. Quando l'agente è configurato per importare contenuti JSON, l'input deve essere formattato in modo che ogni oggetto JSON si trovi su una nuova riga: 

    {"name" : "zeeshan", "age" : 28}
    {"name" : "reeba", "age" : 15}

Per configurare l'agente Logging in modo che importi contenuti in formato JSON, segui questi passaggi:

  1. Dal prompt dei comandi di Linux, crea un file di log:

    touch /tmp/test-structured-log.log

  2. Crea un nuovo file di configurazione denominato test-structured-log.conf nella directory di configurazione aggiuntiva /etc/google-fluentd/config.d:

    sudo tee /etc/google-fluentd/config.d/test-structured-log.conf <<EOF
<source>
    @type tail
    <parse>
        # 'json' indicates the log is structured (JSON).
        @type json
    </parse>
    # The path of the log file.
    path /tmp/test-structured-log.log
    # The path of the position file that records the position in the log
    # file that has already been processed. 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>
  EOF

    Un'alternativa alla creazione di un nuovo file è aggiungere le informazioni di configurazione a un file di configurazione esistente.

  3. Riavvia l'agente per applicare le modifiche alla configurazione:

    sudo service google-fluentd restart

  4. Genera un record di log nel file di log:

    echo '{"code": "structured-log-code", "message": "This is a log from the log file at test-structured-log.log"}' >> /tmp/test-structured-log.log

  5. Controlla Esplora log per visualizzare la voce di log importata:

    {
  insertId:  "1m9mtk4g3mwilhp"
  jsonPayload: {
  code:  "structured-log-code"
  message:  "This is a log from the log file at test-structured-log.log"
  }
  labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/structured-log"
  receiveTimestamp:  "2018-03-21T01:53:41.118200931Z"
  resource: {
  labels: {
    instance_id:  "5351724540900470204"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
  }
  timestamp:  "2018-03-21T01:53:39.071920609Z"
}

    In Esplora log, filtra per tipo di risorsa e un logName di structured-log.

Per ulteriori opzioni di personalizzazione del formato di input dei log per le applicazioni di terze parti più comuni, consulta Formati di log comuni e come analizzarli.

Streaming di log strutturati (JSON) utilizzando il plug-in in_forward

Inoltre, puoi inviare i log utilizzando il plug-in fluentd in_forward. fluentd-cat è uno strumento integrato che aiuta a inviare i log al plug-in in_forward. La documentazione di fluentd contiene ulteriori dettagli su questo strumento.

Per inviare i log utilizzando il plug-in in_forward fluentd, leggi le seguenti istruzioni:

  1. Esegui questo comando sulla VM con l'agente Logging installato:

    echo '{"code": "send-log-via-fluent-cat", "message": "This is a log from in_forward plugin."}' | /opt/google-fluentd/embedded/bin/fluent-cat log-via-in-forward-plugin

  2. Controlla Esplora log per visualizzare la voce di log importata:

    {
  insertId:  "1kvvmhsg1ib4689"
  jsonPayload: {
  code:  "send-log-via-fluent-cat"
  message:  "This is a log from in_forward plugin."
  }
  labels: {
  compute.googleapis.com/resource_name:  "add-structured-log-resource"
  }
  logName:  "projects/my-sample-project-12345/logs/log-via-in-forward-plugin"
  receiveTimestamp:  "2018-03-21T02:11:27.981020900Z"
  resource: {
  labels: {
    instance_id:  "5351724540900470204"
    project_id:  "my-sample-project-12345"
    zone:  "us-central1-c"
  }
  type:  "gce_instance"
  }
  timestamp:  "2018-03-21T02:11:22.717692494Z"
}

Streaming di record di log strutturati (JSON) dal codice dell'applicazione

Puoi abilitare i connettori in vari linguaggi per inviare log strutturati dal codice dell'applicazione. Per saperne di più, consulta la documentazione di fluentd. Questi connettori si basano sul plug-in in_forward.

Impostazione delle etichette voce di log

Le seguenti opzioni di configurazione consentono di eseguire l'override delle etichette LogEntry e MonitoredResource durante l'importazione dei log in Cloud Logging. Tutte le voci di log sono associate a risorse monitorate. Per ulteriori informazioni, consulta l'elenco dei tipi di risorsa monitorata di Cloud Logging.

Nome della configurazione Tipo Predefinito Descrizione
label_map hash nil label_map (specificato come oggetto JSON) è un insieme non ordinato di nomi di campi fluentd i cui valori vengono inviati come etichette anziché come parte del payload strutturato. Ogni voce nella mappa è una coppia {field_name: label_name}. Quando viene rilevato field_name (come analizzato dal plug-in di input), alla voce di log viene aggiunta un'etichetta con il valore label_name corrispondente. Il valore del campo viene utilizzato come valore dell'etichetta. La mappa offre una maggiore flessibilità nella specifica dei nomi delle etichette, inclusa la possibilità di utilizzare caratteri che non sarebbero validi come parte dei nomi dei campi fluentd. Per un esempio, consulta Impostazione delle etichette nelle voci di log strutturate.
labels hash nil labels (specificato come oggetto JSON) è un insieme di etichette personalizzate fornite al momento della configurazione. Ti consente di inserire informazioni ambientali aggiuntive in ogni messaggio o di personalizzare le etichette che altrimenti verrebbero rilevate automaticamente. Ogni voce nella mappa è una coppia {label_name: label_value}.

Il plug-in di output dell'agente Logging supporta due modi per impostare le etichette LogEntry:

Impostazione delle etichette nelle voci di log strutturate

Supponiamo che tu abbia scritto un payload di voce di log strutturata come questo:

{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }

Supponiamo che tu voglia tradurre il campo del payload env in un'etichetta dei metadati environment. Per farlo, aggiungi quanto segue alla configurazione del plug-in di output nel file di configurazione principale (/etc/google-fluentd/google-fluentd.conf su Linux o C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf su Windows):

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  label_map {
    "env": "environment"
  }
  ...
</match>

L'impostazione label_map qui sostituisce l'etichetta env nel payload con environment, quindi la voce di log risultante ha un'etichetta environment con il valore production.

Impostazione statica delle etichette

Se non hai queste informazioni nel payload e vuoi aggiungere un'etichetta di metadati statica denominata environment, aggiungi quanto segue alla configurazione del plug-in di output nel file di configurazione principale (/etc/google-fluentd/google-fluentd.conf su Linux o C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf su Windows):

# Configure all sources to output to Cloud Logging
<match **>
  @type google_cloud
  labels {
    "environment": "production"
  }
  ...
</match>

In questo caso, anziché utilizzare una mappa per sostituire un'etichetta con un'altra, utilizziamo un'impostazione labels per allegare un'etichetta con un determinato valore letterale a una voce di log, indipendentemente dal fatto che la voce abbia già un'etichetta o meno. Questo approccio può essere utilizzato anche se invii log non strutturati.

Per saperne di più su come configurare labels, label_map e altre impostazioni dell'agente Logging, consulta la sezione Impostazione delle etichette delle voci di log di questa pagina.

Modifica dei record di log

Fluentd fornisce plug-in di filtro integrati che possono essere utilizzati per modificare le voci di log.

Il plug-in di filtro di uso comune è filter_record_transformer. Ti consente di svolgere le seguenti operazioni:

  • Aggiungi nuovi campi alle voci di log
  • Aggiorna i campi nelle voci di log
  • Elimina i campi nelle voci di log

Alcuni plug-in di output consentono anche di modificare le voci di log. Il plug-in di output fluent-plugin-record-reformer fornisce funzionalità simili a quelle del plug-in di filtro filter_record_transformer, con la differenza che consente anche di modificare i tag dei log. Con questo plug-in è previsto un maggiore utilizzo delle risorse: ogni volta che un tag di log viene aggiornato, viene generata una nuova voce di log con il nuovo tag. Tieni presente che il campo tag nella configurazione è obbligatorio. Ti consigliamo inoltre di modificare questo campo per evitare di entrare in un loop infinito.

Il plug-in di output fluent-plugin-detect-exceptions analizza un flusso di log, ovvero record di log non strutturati (testo) o in formato JSON, per individuare analisi dello stack di eccezioni su più righe. Se una sequenza consecutiva di voci di log forma un'analisi dello stack di eccezioni, le voci di log vengono inoltrate come un unico messaggio di log combinato. In caso contrario, la voce di log viene inoltrata così com'è.

Definizioni di configurazione avanzata (non predefinita)

Se vuoi personalizzare la configurazione dell'agente Logging, oltre alla configurazione predefinita, continua a leggere questa pagina.

Le seguenti opzioni di configurazione consentono di regolare il meccanismo di buffering interno dell'agente Logging.

Nome della configurazione Tipo Predefinito Descrizione
buffer_type string buf_memory I record che non possono essere scritti nell'API Logging abbastanza velocemente vengono inseriti in un buffer. Il buffer può essere in memoria o nei file. Valore consigliato: buf_file. Il valore predefinito buf_memory è veloce, ma non permanente. Esiste il rischio di perdere i log. Se buffer_type è buf_file, è necessario specificare anche buffer_path.
buffer_path string Specificato dall'utente Il percorso in cui sono archiviati i blocchi del buffer. Questo parametro è obbligatorio se buffer_type è buf_file. Questa configurazione deve essere univoca per evitare una race condition.
buffer_queue_limit int 64 Specifica il limite di lunghezza della coda di chunk. Quando la coda di buffer raggiunge questo limite, il comportamento del buffer è controllato da buffer_queue_full_action. Per impostazione predefinita, genera eccezioni. Questa opzione, in combinazione con buffer_chunk_limit, determina lo spazio su disco massimo utilizzato da fluentd per il buffering.
buffer_queue_full_action string exception Controlla il comportamento del buffer quando la coda di buffer è piena. Valori possibili:
1. exception: Genera BufferQueueLimitError quando la coda è piena. Il modo in cui viene gestito BufferQueueLimitError dipende dai plug-in di input. Ad esempio, il plug-in di input in_tail interrompe la lettura delle nuove righe, mentre il plug-in di input in_forward restituisce un errore.
2. block: questa modalità interrompe il thread del plug-in di input finché non viene risolta la condizione di buffer pieno. Questa azione è utile per i casi d'uso simili ai batch. fluentd sconsiglia di utilizzare l'azione di blocco per evitare BufferQueueLimitError. Se visualizzi spesso BufferQueueLimitError, significa che la capacità della destinazione non è sufficiente per il tuo traffico.
3. drop_oldest_chunk: questa modalità elimina i chunk meno recenti.

Opzioni di configurazione relative al progetto e alle risorsa monitorata

Le seguenti opzioni di configurazione ti consentono di specificare manualmente un progetto e determinati campi dall'oggetto MonitoredResource. Questi valori vengono raccolti automaticamente dall'agente Logging; non è consigliabile specificarli manualmente.

Nome della configurazione Tipo Predefinito Descrizione
project_id string nil Se specificato, questo valore sostituisce il project_id che identifica il progetto Google Cloud o AWS sottostante in cui è in esecuzione l'agente Logging.
zone string nil Se specificato, questo valore sostituisce la zona.
vm_id string nil Se specificato, questo valore sostituisce l'ID VM.
vm_name string nil Se specificato, questo valore sostituisce il nome della VM.

Altre opzioni di configurazione del plug-in di output

Nome della configurazione Tipo Predefinito Descrizione
detect_json1 bool false Indica se tentare di rilevare se il record di log è una voce di log di testo con contenuti JSON che devono essere analizzati. Se questa opzione è true e viene rilevata una voce di log non strutturata (testo) in formato JSON, questa viene analizzata e inviata come payload strutturato (JSON).
coerce_to_utf8 bool true Indica se consentire caratteri non UTF-8 nei log utente. Se impostato su true, qualsiasi carattere non UTF-8 viene sostituito dalla stringa specificata da non_utf8_replacement_string. Se impostato su false, qualsiasi carattere non UTF-8 causa un errore del plug-in.
require_valid_tags bool false Indica se rifiutare le voci di log con tag non validi. Se questa opzione è impostata su false, i tag vengono resi validi convertendo qualsiasi tag non stringa in una stringa e sanitizzando i caratteri non UTF-8 o altri caratteri non validi.
non_utf8_replacement_string string "" (stringa vuota) o " "(spazio) Se coerce_to_utf8 è impostato su true, qualsiasi carattere non UTF-8 viene sostituito dalla stringa specificata qui.

1 Questa funzionalità è attivata per impostazione predefinita nelle istanze VM in esecuzione nell'ambiente flessibile App Engine.

Applicazione della configurazione dell'agente personalizzata

La personalizzazione dell'agente Logging ti consente di aggiungere i tuoi file di configurazione fluentd:

Istanza Linux

  1. Copia i file di configurazione nella seguente directory:

    /etc/google-fluentd/config.d/

    Lo script di installazione dell'agente Logging compila questa directory con i file di configurazione catch-all predefiniti. Per saperne di più, consulta Recupero del codice sorgente dell'agente Logging.

  2. Facoltativo. Convalida la modifica della configurazione eseguendo questo comando:

    sudo service google-fluentd configtest

  3. Riavvia l'agente eseguendo questo comando:

    sudo service google-fluentd force-reload

Istanza Windows

  1. Copia i file di configurazione nella sottodirectory config.d della directory di installazione dell'agente. Se hai accettato la directory di installazione predefinita, questa directory è:

    C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\

  2. Riavvia l'agente eseguendo i seguenti comandi in una shell della riga di comando:

    net stop StackdriverLogging
net start StackdriverLogging

Per ulteriori informazioni sui file di configurazione di fluentd, consulta la documentazione sulla sintassi dei file di configurazione di fluentd.