Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Configurazione dell'agente Logging

Questa pagina fornisce dettagli sulle configurazioni predefinite e personalizzate dell'agente Cloud Logging.

La maggior parte degli utenti non ha bisogno di leggere questa pagina. Leggi questa pagina se:

Ti interessa conoscere i dettagli tecnici approfonditi della configurazione dell'agente Cloud Logging.
Vuoi modificare la configurazione dell'agente Cloud Logging.

Configurazione predefinita

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

Nella sua 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, vedi Personalizzare la 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 degli eventi da origini esterne, ad esempio file su disco, o per analizzare i record di log in entrata. I plug-in di input sono inclusi nell'agente o possono essere installati separatamente come gemme Ruby. Consulta l'elenco dei plug-in inclusi.

L'agente legge i record di log archiviati nei file di log sull'istanza VM tramite il plug-in in_tail integrato di fluentd. Ogni record di log viene convertito in una struttura di voce di log per Cloud Logging. Il contenuto di ogni record di log viene registrato 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 taggato con un tag in formato stringa; tutti i plug-in di query e 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 del 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 testo o il payload 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, ad esempio quelli nell'elenco dei log predefiniti e il nostro 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 esegui un agente Logging precedente alla versione 1-5, la posizione è: C:\GoogleStackdriverLoggingAgent\fluent.conf

Configurazione Syslog

Percorsi 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 `fluentd`documentazione dettagliata.
`read_from_head`	bool	`true`	Indica se iniziare a leggere i log dall'inizio del file anziché dalla fine. Consulta la `fluentd`documentazione dettagliata.
`tag`	string	`syslog`	Il tag di log per questo input di log.

`in_forward` input plugin configuration

Percorsi dei file di configurazione: /etc/google-fluentd/config.d/forward.conf
Descrizione: questo file include la configurazione per configurare il plug-in di input in_forward fluentd. Il plug-in di input in_forward ti consente di passare i log tramite un socket TCP.
Consulta la documentazione fluentd dettagliata 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 binding da monitorare. Per impostazione predefinita, vengono accettate solo le connessioni da localhost. Per aprirlo, questa configurazione deve essere modificata in `0.0.0.0`.

Configurazione dell'input dei log delle applicazioni di terze parti

Percorsi dei file di configurazione: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
Description: questa directory include 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 es. apache.conf per l'applicazione Apache).
Esamina il repository di configurazione.

Nome della configurazione	Tipo	Predefinito	Descrizione
`format`¹	string	Varia in base all'applicazione	Il formato del log. Consulta la `fluentd`documentazione dettagliata.
`path`	string	Varia in base all'applicazione	Il percorso dei file di log. È possibile specificare più percorsi separati da ",". È possibile includere i formati * e strftime per aggiungere/rimuovere dinamicamente il file di monitoraggio. Consulta la `fluentd`documentazione dettagliata.
`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 `fluentd` dettagliata.
`read_from_head`	bool	`true`	Indica se iniziare a leggere i log dall'inizio del file anziché dalla fine. Consulta la `fluentd`documentazione dettagliata.
`tag`	string	Varia; il nome dell'applicazione.	Il tag di log per questo input di log.

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

Google Cloud `fluentd` configurazione del plug-in di output

Percorsi dei file di configurazione:
- Linux: /etc/google-fluentd/google-fluentd.conf
- Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf
  
  Se esegui 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 arrivano i record di log, 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 blocco. Per impostazione predefinita, il limite dei chunk viene impostato in modo prudente per evitare di superare le dimensioni consigliate di 5 MB per richiesta di scrittura nell'API Logging. Le voci di log nella richiesta API possono essere 5-8 volte più grandi delle dimensioni originali del log con tutti i metadati aggiuntivi allegati. Un blocco buffer viene svuotato se è soddisfatta una delle due condizioni: 1. `flush_interval` entra in vigore. 2. La dimensione del buffer raggiunge `buffer_chunk_limit`.
`flush_interval`	string	`5s`	Man mano che arrivano i record di log, 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 di dover svuotare un buffer di chunk. Un blocco buffer viene svuotato se è soddisfatta una delle due condizioni: 1. `flush_interval` entra in vigore. 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. Consulta le specifiche dettagliate in `retry_limit`, `retry_wait` e `max_retry_wait`.
`retry_limit`	int	`3`	Quando un blocco buffer non viene scaricato, `fluentd` per impostazione predefinita riprova in un secondo momento. Questa configurazione imposta il numero di tentativi da eseguire prima di eliminare un blocco del buffer problematico.
`retry_wait`	int	`10s`	Quando un blocco buffer non viene scaricato, `fluentd` per impostazione predefinita riprova in un secondo momento. Questa configurazione imposta l'intervallo di attesa in secondi prima del primo tentativo. L'intervallo di attesa raddoppia a ogni nuovo tentativo (20 secondi, 40 secondi e così via) finché non viene raggiunto `retry_ limit` o `max_retry_wait`.
`max_retry_wait`	int	`300`	Quando un blocco buffer non viene scaricato, `fluentd` per impostazione predefinita riprova in un secondo momento. L'intervallo di attesa raddoppia a ogni tentativo successivo (20 secondi, 40 secondi e così via). Questa configurazione imposta il massimo degli intervalli di attesa in secondi. Se l'intervallo di attesa raggiunge questo limite, il raddoppio si interrompe.
`num_threads`	int	`8`	Il numero di scarichi simultanei dei log 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 completamento parziale dell'importazione dei log. Se `true`, le voci di log non valide in un set completo vengono eliminate e le voci di log valide vengono importate correttamente nell'API Logging. Se `false`, l'intero set verrebbe eliminato 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 del plug-in di output.
`monitoring_type`	string	`opencensus`	Il tipo di monitoraggio. Le opzioni supportate sono `opencensus` e `prometheus`. Per maggiori dettagli, consulta Telemetria del plug-in di output.
`autoformat_stackdriver_trace`	bool	`true`	Se impostato 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

Telemetria del plug-in di output

L'opzione enable_monitoring controlla se il plug-in di output Google Cloud fluentd raccoglie la telemetria interna. Se impostato su true, l'agente Loggingg tiene traccia del numero di voci di log richieste da inviare a Cloud Logging e del numero effettivo di voci di log inserite 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. Consulta l'elenco delle metriche riportato di seguito.

Se impostato su prometheus, l'agente Logging espone le metriche in formato Prometheus sull'endpoint Prometheus (localhost:24231/metrics per impostazione predefinita; consulta Configurazione dei plug-in prometheus e prometheus_monitor per informazioni dettagliate sulla personalizzazione). Affinché queste metriche vengano scritte nell'API Monitoring sulle VM di Compute Engine, è necessario installare ed eseguire anche l'agente Monitoring.

Se impostato su opencensus (impostazione predefinita a partire 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 all'account di servizio 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: Tempo di attività dell'agente Logging.
agent.googleapis.com/agent/log_entry_count con un'etichetta response_code: Numero di voci di log scritte dall'agente Logging.
agent.googleapis.com/agent/log_entry_retry_count con un'etichetta response_code: Numero di 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 modo più dettagliato nella pagina Metriche degli agenti.

Inoltre, il plug-in di output espone le seguenti metriche Prometheus in modalità prometheus:

uptime con un'etichetta version: Tempo di attività 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 la cui importazione non è riuscita a causa di un errore temporaneo e per le quali è stato eseguito un nuovo tentativo. Google Cloud fluentd

Configurazione dei plug-in prometheus e prometheus_monitor

Percorsi 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 del plug-in google_cloud sopra, tramite una porta locale in formato Prometheus. Per ulteriori dettagli, visita la pagina https://docs.fluentd.org/deployment/monitoring-prometheus.
Vai al repository di configurazione.

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

# 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 inserita come payload non strutturati (testo) nelle voci di log.

L'unica eccezione è il plug-in di input in_forward, anch'esso abilitato per impostazione predefinita, che accetta solo log strutturati e li inserisce come payload strutturati (JSON) nelle voci di log. Per maggiori dettagli, leggi Streaming di record di log strutturati (JSON) tramite 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 e in Google Kubernetes Engine. Questa opzione non è abilitata per impostazione predefinita nelle istanze VM in esecuzione nell'ambiente standard di App Engine. Qualsiasi JSON analizzato con l'opzione detect_json attivata viene sempre importato come jsonPayload.

Puoi personalizzare la configurazione degli agent per supportare l'importazione di log strutturati da risorse aggiuntive. Per maggiori dettagli, consulta Trasmettere in streaming i record di log strutturati (JSON) a Cloud Logging.

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

Campi speciali nei payload strutturati

Quando lagente 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 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 log JSON	`LogEntry` campo	Funzione dell'agente Cloud Logging	Valore di esempio
`severity`	`severity`	L'agente Logging tenta di trovare corrispondenze 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 di logging sposta gli altri campi speciali e `detect_json` non è stato attivato; altrimenti `message` rimane in `jsonPayload`. `detect_json` non è applicabile agli ambienti di logging gestiti come 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 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 per scopi speciali, rimane solo un campo `log`, questo viene salvato come `textPayload`.
`httpRequest`	`httpRequest`	Un record strutturato nel formato del campo `LogEntry` `HttpRequest`.	`"httpRequest":{"requestMethod":"GET"}`
campi correlati al tempo	`timestamp`	Per saperne di più, vedi Campi relativi all'ora.	`"time":"2020-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 ulteriori informazioni, 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 ulteriori informazioni, consulta la sezione `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 della traccia associata alla voce di log, se presente. Per saperne di più, consulta `trace` nella pagina `LogEntry`.	`"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"` Nota: se non scrivi su `stdout` o `stderr`, il valore di questo campo deve essere formattato come `projects/[PROJECT-ID]/traces/[TRACE-ID]`, in modo che possa essere utilizzato da Logs Explorer e Trace Viewer per raggruppare le voci di log e visualizzarle in linea con le tracce. Se `autoformat_stackdriver_trace` è true e `[V]` corrisponde al formato di ResourceTrace `traceId` 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 correlati al tempo

In generale, le informazioni relative all'ora 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 informazioni relative all'ora nei campi della voce jsonPayload:

Cerca un campo timestamp che sia un oggetto JSON che includa i campi seconds e nanos, che rappresentano, rispettivamente, un numero di secondi firmato dall'epoca UTC e un numero non negativo di secondi frazionari:
```
jsonPayload: {
  ...
  "timestamp": {
    "seconds": CURRENT_SECONDS,
    "nanos": CURRENT_NANOS
  }
}
```
Se la ricerca precedente non va a buon fine, cerca una coppia di campi timestampSeconds e timestampNanos:
```
jsonPayload: {
  ...
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS
}
```
Se la ricerca precedente non va a buon fine, cerca un campo time che sia una stringa nel formato RFC 3339:
```
jsonPayload: {
  ...
  "time": CURRENT_TIME_RFC3339
}
```

Quando vengono trovate informazioni relative all'ora, 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 correlati all'ora 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 in streaming per impostazione predefinita, puoi personalizzare l'agente Logging per inviare log aggiuntivi a Logging o per 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 come 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 esegui 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.

Streaming dei log da input aggiuntivi

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

Streaming dei log non strutturati (di testo) tramite i file di log

Dal prompt dei comandi di Linux, crea un file di log:
```
touch /tmp/test-unstructured-log.log
```

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 where in the log file
    # we have processed already. 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 è l'aggiunta delle informazioni di configurazione a un file di configurazione esistente.

Riavvia l'agente per applicare le modifiche alla configurazione:
```
sudo service google-fluentd restart
```

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

Controlla Esplora log per visualizzare la voce di log inserita:

{
  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) tramite 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 l'importazione di 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 acquisisca contenuti in formato JSON, svolgi le seguenti operazioni:

Dal prompt dei comandi di Linux, crea un file di log:
```
touch /tmp/test-structured-log.log
```

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 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>
  EOF

Un'alternativa alla creazione di un nuovo file è l'aggiunta delle informazioni di configurazione a un file di configurazione esistente.

Riavvia l'agente per applicare le modifiche alla configurazione:
```
sudo service google-fluentd restart
```

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

Controlla Esplora log per visualizzare la voce di log inserita:

{
  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 per logName di structured-log.

Per ulteriori opzioni per personalizzare il formato di input dei log per applicazioni di terze parti comuni, consulta Formati di log comuni e come analizzarli.

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

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

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

Esegui il seguente 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

Controlla Esplora log per visualizzare la voce di log inserita:

{
  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 attivare i connettori in varie lingue per inviare log strutturati dal codice dell'applicazione. Per ulteriori informazioni, consulta la documentazione fluentd. Questi connettori sono creati in base al plug-in in_forward.

Impostazione delle etichette voce di log

Le seguenti opzioni di configurazione ti consentono di sostituire le etichette LogEntry e MonitoredResource durante l'importazione dei log in Cloud Logging. Tutte le voci di log sono associate a risorse monitorate. Per saperne di più, 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` (analizzato dal plug-in di input), viene aggiunta all'voce di log un'etichetta con il `label_name` corrispondente. Il valore del campo viene utilizzato come valore dell'etichetta. La mappa offre maggiore flessibilità nella specifica dei nomi delle etichette, inclusa la possibilità di utilizzare caratteri che non sarebbero legali come parte dei nomi dei campi `fluentd`. Per un esempio, vai a 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 rilevate automaticamente. Ogni voce nella mappa è una coppia {`label_name`: `label_value`}.

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

In modo dinamico, sostituendo etichette specifiche in una voce strutturata con etichette diverse. Per maggiori dettagli, vedi Impostazione delle etichette nelle voci di log strutturate in questa pagina.
In modo statico, allegando un'etichetta a qualsiasi occorrenza di un valore. Per maggiori dettagli, vedi Impostare le etichette in modo statico in questa pagina.

Impostazione delle etichette nelle voci di log strutturate

Supponiamo di aver scritto un payload di voce di log strutturato come questo:

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

Supponiamo di voler tradurre il campo payload env in un'etichetta di 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 semplicemente aggiungere un'etichetta di metadati statica chiamata 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&#39agente Loggingg, vai a Impostare le etichette delle voci di log in 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 filtri più utilizzato è filter_record_transformer. Ti consente di:

Aggiungere nuovi campi alle voci di log
Aggiornare i campi nelle voci di log
Eliminare 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 al plug-in di filtro filter_record_transformer, tranne per il fatto che consente anche di modificare i tag dei log. Con questo plug-in è previsto un maggiore utilizzo delle risorse: ogni volta che un tag 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 ciclo senza fine.

Il plug-in di output fluent-plugin-detect-exceptions analizza un flusso di log, record di log non strutturati (testo) o in formato JSON, alla ricerca di tracce di stack di eccezioni su più righe. Se una sequenza consecutiva di voci di log forma una 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.

Opzioni di configurazione relative al buffer

Le seguenti opzioni di configurazione ti 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 rapidamente vengono inseriti in un buffer. Il buffer può essere in memoria o in file effettivi. Valore consigliato: `buf_file`. Il `buf_memory` predefinito è veloce, ma non persistente. 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` è `file`. Questa configurazione deve essere univoca per evitare una race condition.
`buffer_queue_limit`	int	`64`	Specifica il limite di lunghezza della coda di blocchi. Quando la coda di buffer raggiunge questo numero di segmenti, 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 del buffer è piena. Valori possibili: 1. `exception`: genera `BufferQueueLimitError` quando la coda è piena. La gestione di `BufferQueueLimitError` dipende dai plug-in di input. Ad esempio, il plug-in di input `in_tail` interrompe la lettura di 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é la condizione di buffer pieno non viene risolta. Questa azione è adatta ai casi d'uso simili ai batch. `fluentd` non consiglia di utilizzare l'azione di blocco per evitare `BufferQueueLimitError`. Se visualizzi spesso l'errore `BufferQueueLimitError`, significa che la capacità della destinazione è insufficiente 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 dell'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 `project_id` che identifica il progetto sottostante Google Cloud o AWS 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_json`¹	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 una voce di log non strutturata (testo) viene rilevata in formato JSON, viene analizzata e inviata come payload strutturato (JSON).
`coerce_to_utf8`	bool	`true`	Specifica 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 attiverà l'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 sanificando qualsiasi carattere non UTF-8 o non valido.
`non_utf8_replacement_string`	string	`""`(spazio)	Se `coerce_to_utf8` è impostato su `true`, qualsiasi carattere non UTF-8 verrà sostituito dalla stringa specificata qui.

¹ Questa funzionalità è abilitata per impostazione predefinita nelle istanze VM in esecuzione nell'ambiente flessibile di App Engine e in Google Kubernetes Engine.

Applicazione della configurazione dell'agente personalizzata

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

Istanza Linux

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 Ottenere il codice sorgente dell'agente Logging.
Facoltativo. Convalida la modifica alla configurazione eseguendo questo comando:
```
sudo service google-fluentd configtest
```

Riavvia l'agente eseguendo questo comando:

sudo service google-fluentd force-reload

Istanza Windows

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\
```
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 fluentd, consulta la documentazione sulla sintassi del file di configurazione di fluentd.

Configurazione dell'agente Logging Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Configurazione predefinita

Definizioni di configurazione predefinite

Posizione del file di configurazione principale

Configurazione Syslog

in_forward input plugin configuration

Configurazione dell'input dei log delle applicazioni di terze parti

Google Cloud fluentd configurazione del plug-in di output

Configurazione del monitoraggio

Telemetria del plug-in di output

Configurazione dei plug-in prometheus e prometheus_monitor

Elaborazione dei payload

Campi speciali nei payload strutturati

Campi correlati al tempo

Personalizzazione della configurazione dell'agente

Streaming dei log da input aggiuntivi

Streaming dei log non strutturati (di testo) tramite i file di log

Streaming di log strutturati (JSON) tramite file di log

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

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

Impostazione delle etichette voce di log

Impostazione delle etichette nelle voci di log strutturate

Impostazione statica delle etichette

Modifica dei record di log

Definizioni di configurazione avanzata (non predefinita)

Opzioni di configurazione relative al buffer

Opzioni di configurazione relative al progetto e alle risorsa monitorata

Altre opzioni di configurazione del plug-in di output

Applicazione della configurazione dell'agente personalizzata

Istanza Linux

Istanza Windows

Configurazione dell'agente Logging

`in_forward` input plugin configuration

Google Cloud `fluentd` configurazione del plug-in di output

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