Questa pagina è stata tradotta dall'API Cloud Translation.

Configurazione dell'agente Logging

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

La maggior parte degli utenti non deve leggere questa pagina. Leggi questa pagina se:

Ti interessano dettagli tecnici approfonditi sulla configurazione dell'agente Cloud Logging.
Vuoi modificare la configurazione dell'agente Cloud Logging.

Configurazione predefinita

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

Nella configurazione predefinita, l'agente Logging invia il flusso di log, inclusi nell'elenco dei log predefiniti, in Cloud Logging. Puoi configurare l'agente per inviare log aggiuntivi in modalità flusso. per i dettagli, vai a Personalizzazione della configurazione dell'agente Logging in questa pagina.

Come funziona l'agente Logging.

L'agente Logging utilizza fluentd plug-in di input per recupera ed esegui il pull dei log eventi da origini esterne, come file su disco per analizzare i record dei log in entrata. I plug-in di input vengono abbinati all'agente oppure possono essere installate separatamente come gemme Ruby; rivedi l'elenco plug-in in bundle.

L'agente legge i record dei log memorizzati nei file di log sull'istanza VM tramite il plug-in in_tail integrato di fluentd. Ogni record di log viene convertito in un Struttura delle voci di log per e in Cloud Logging. I contenuti di ogni record del log vengono registrati principalmente nel payload delle voci di log, ma queste ultime contengono anche elementi standard come un timestamp e la gravità. L'agente di 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. Nome log di solito segue questo formato, projects/[PROJECT-ID]/logs/[TAG]. Ad esempio, questo nome log include Tag structured-log:

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

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

Le sezioni seguenti di questa pagina illustrano 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 inoltrato, le configurazioni di input per i log delle applicazioni di terze parti, come quelli nell'elenco dei log predefiniti, e il nostro plug-in di output fluentd di Google Cloud.

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 /etc/google-fluentd/config.d cartella.
Windows: C:\Program Files (x86)\Stackdriver\LoggingAgent\fluent.conf

Se esegui un agente Logging prima della versione 1-5, la località è: C:\GoogleStackdriverLoggingAgent\fluent.conf

Configurazione di Syslog

Posizioni del 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 di `fluentd` dettagliata.
`tag`	string	`syslog`	Il tag log per questo input log.

Configurazione plug-in di input `in_forward`

Località 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 ti consente di trasmettere i log tramite una socket TCP.
Esamina la documentazione di 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 associazione 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 di applicazioni di terze parti

Località dei file di configurazione: /etc/google-fluentd/config.d/[APPLICATION_NAME].conf
Descrizione: 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, rappresentano 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 documentazione di `fluentd` dettagliata.
`path`	string	Varia in base all'applicazione	Il percorso dei file di log. È possibile specificare più percorsi, separati da ",". È possibile includere * e il formato strftime per aggiungere/rimuovere dinamicamente il file di monitoraggio. 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'intestazione del file anziché dal basso. Consulta la documentazione dettagliata di `fluentd`.
`tag`	string	Varia; il nome dell'applicazione.	Il tag di log per questo input di log.

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

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

Posizione 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 prima della versione 1-5, la località è: C:\GoogleStackdriverLoggingAgent\fluent.conf
Descrizione: questo file include opzioni di configurazione per controllare il comportamento del plug-in di output fluentd di Google Cloud.
Vai al repository di configurazione.

Nome della configurazione	Tipo	Predefinito	Descrizione
`buffer_chunk_limit`	string	`512KB`	Quando arrivano i record di log, quelli che non possono essere scritti sui componenti downstream con una velocità sufficiente vengono inseriti in una coda di chunk. Questa configurazione imposta il limite di dimensioni di ogni chunk. Per impostazione predefinita, impostiamo il limite di blocchi in modo conservativo per evitare di superare la dimensione consigliata del chunk di 5 MB per ogni richiesta di scrittura nell'API Logging. Le voci di log nella richiesta API possono essere da 5 a 8 volte più grandi rispetto alla dimensione originale del log con tutti i metadati aggiuntivi allegati. Un chunk del buffer viene svuotato se è soddisfatta una delle due condizioni: 1. `flush_interval` viene attivato. 2. La dimensione del buffer raggiunge `buffer_chunk_limit`.
`flush_interval`	string	`5s`	Quando arrivano i record di log, quelli che non possono essere scritti sui componenti downstream con una velocità sufficiente vengono inseriti in una coda di chunk. La configurazione imposta il tempo che deve trascorrere prima di svuotare un buffer di chunk. Un chunk del buffer viene svuotato se è soddisfatta una delle due condizioni: 1. Interessa `flush_interval`. 2. La dimensione del buffer raggiunge `buffer_chunk_limit`.
`disable_retry_limit`	bool	`false`	Applica un limite al numero di nuovi tentativi di svuotamento dei blocchi del buffer non riusciti. Consulta le specifiche dettagliate in `retry_limit`, `retry_wait` e `max_retry_wait`.
`retry_limit`	int	`3`	Quando non è possibile svuotare un blocco di buffer, `fluentd` per impostazione predefinita esegue un nuovo tentativo 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 svuotare un chunk del buffer, per impostazione predefinita `fluentd` 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 tentativo successivo (20, 40 s,...) fino a quando non viene raggiunto `retry_ limit` o `max_retry_wait`.
`max_retry_wait`	int	`300`	Quando non è possibile svuotare un blocco di buffer, `fluentd` per impostazione predefinita esegue un nuovo tentativo in un secondo momento. L'intervallo di attesa raddoppia a ogni nuovo tentativo (20 secondi, 40 secondi e così via). Questa configurazione imposta il numero massimo di intervalli di attesa in secondi. Se l'intervallo di attesa raggiunge questo limite, il raddoppio si interrompe.
`num_threads`	int	`8`	Il numero di svuotamenti simultanei di 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 l'esito positivo parziale per l'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 verrà eliminato se contiene voci di log non valide.
`enable_monitoring`	bool	`true`	Se impostato su `true`, l'agente Logging esporta la telemetria interna. Per maggiori dettagli, consulta la sezione Telemetria dei plug-in di output.
`monitoring_type`	string	`opencensus`	Il tipo di monitoraggio. Le opzioni supportate sono `opencensus` e `prometheus`. Per informazioni dettagliate, 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 payload strutturato `logging.googleapis.com/trace` corrisponde al formato ResourceTrace `traceId`. Puoi trovare i dettagli della formattazione automatica in Campi speciali nei payload strutturati di questa pagina.

Configurazione del monitoraggio

Telemetria plug-in di output

L'opzione enable_monitoring controlla se il plug-in di output fluentd Google Cloud raccoglie la telemetria interna. Se impostato su true, il valore L'agente Logging tiene traccia del numero di voci di log richieste da inviare a Cloud Logging e il numero effettivo di voci di log correttamente importati da Cloud Logging. Se il criterio viene impostato su false, le metriche non vengono raccolte il plug-in di output.

L'opzione monitoring_type controlla il modo in cui questa telemetria è esposta dall'oggetto dell'agente. Consulta l'elenco delle metriche di seguito.

Se impostato su prometheus, l'agente Logging espone le metriche in formato Prometheus nell'endpoint Prometheus (localhost:24231/metrics per impostazione predefinita; consulta la configurazione dei plug-in prometheus e prometheus_monitor per informazioni dettagliate sulla personalizzazione). Per le VM di Compute Engine, le metriche da scrivere nell'API Monitoring, L'agente di monitoraggio ha per l'installazione e l'esecuzione.

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

Le seguenti metriche vengono scritte nell'API Monitoring da entrambi l'agente Monitoring e l'agente Logging Modalità opencensus:

agent.googleapis.com/agent/uptime con etichetta version: Uptime dell'agente Logging.
agent.googleapis.com/agent/log_entry_count con 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: Numero di voci di log scritte dall'agente Logging.
agent.googleapis.com/agent/request_count con un'etichetta response_code: numero di richieste API dall'agente Logging.

Queste metriche sono descritte in modo più dettagliato nella Metriche degli agenti .

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

uptime con etichetta version: Uptime dell'agente Logging.
stackdriver_successful_requests_count con grpc e code etichette: Il numero di richieste riuscite all'API Logging.
stackdriver_failed_requests_count con le etichette grpc e code: Il numero di richieste non riuscite all'API Logging, suddivise per codice di errore.
stackdriver_ingested_entries_count con grpc e code etichette: Il numero di voci di log importate dall'API Logging.
stackdriver_dropped_entries_count con grpc e code etichette: Il numero di voci di log rifiutate dall'API Logging.
stackdriver_retried_entries_count con grpc e code etichette: Il numero di voci di log che non è stato possibile importare da Google Cloud Plug-in di output di fluentd a causa di un errore temporaneo ed è stato riprovato.

Configurazione dei plug-in prometheus e prometheus_monitor

Località dei file di configurazione: /etc/google-fluentd/google-fluentd.conf
Descrizione: Questo file include opzioni di configurazione per controllare il comportamento Plug-in prometheus e prometheus_monitor. Il plug-in prometheus_monitor monitora l'infrastruttura di base di Fluentd. Il plug-in prometheus espone incluse quelle del plug-in prometheus_monitor e quelle dal plug-in google_cloud riportato sopra tramite una porta locale in formato Prometheus. Scopri di più all'indirizzo https://docs.fluentd.org/deployment/monitoring-prometheus.
Vai al repository di configurazione.

Per il monitoraggio di Fluentd, il server delle metriche HTTP di Prometheus integrato è abilitato per impostazione predefinita. Per impedire l'avvio di questo endpoint, puoi rimuovere la sezione seguente 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 di logging proviene da file di log e viene importata come payload non strutturati (di testo) nelle voci di log.

L'unica eccezione è che il plug-in di input in_forward, che è attivato anche per impostazione predefinita, accetta solo log strutturati e li importa come payload strutturati (JSON) nelle voci di log. Per maggiori dettagli, leggi Streaming dei record dei 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 è attivata da predefinito nelle istanze VM in esecuzione nell'ambiente flessibile di App Engine 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 abilitata viene sempre importata come jsonPayload.

Puoi personalizzare la configurazione degli agenti per supportare l'importazione log strutturati da risorse aggiuntive. Per maggiori dettagli, consulta Eseguire lo streaming dei record dei log strutturati (JSON) in Cloud Logging.

Il payload dei record di log in streaming da un agente di 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 di 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 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.

Log JSON campo	`LogEntry` campo	Cloud Logging funzione agente	Valore di esempio
`severity`	`severity`	Il logging un agente tenta di abbinare le stringhe con gravità comune, che includono l'elenco di LogSeverity stringhe riconosciute l'API Logging.	`"severity":"ERROR"`
`message`	`textPayload` (o parte di `jsonPayload`)	Il messaggio visualizzato nella riga di inserimento del 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 ha spostato gli altri campi per scopi speciali e `detect_json` non è stato attivato; in caso contrario, `message` rimane in `jsonPayload`. `detect_json` non è applicabile agli annunci gestiti di logging come Google Kubernetes Engine. Se la voce di log contiene un analisi dello stack delle eccezioni, l'analisi dello stack delle eccezioni essere impostata in questo campo di log JSON di `message`, in modo che l'eccezione l'analisi dello stack può essere analizzata e salvata in Error Reporting.
`log` (legacy Google Kubernetes Engine )	`textPayload`	Si applica solo a Google Kubernetes Engine precedente: 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 di `LogEntry` `HttpRequest`.	`"httpRequest":{"requestMethod":"GET"}`
correlato al tempo campi	`timestamp`	Per ulteriori informazioni, consulta Campi relativi al tempo.	`"time":"2020-10-12T07:20:50.52Z"`
`logging.googleapis.com/insertId`	`insertId`	Per ulteriori informazioni, vedi `insertId` sulla 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, vedi `labels` attivo la 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 Logs Explorer per raggruppare le voci di log correlate. Per ulteriori informazioni, 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 associata all'eventuale voce di log. Per ulteriori informazioni, vedi `LogEntrySourceLocation` sulla pagina `LogEntry`.	`"logging.googleapis.com/sourceLocation":` `{"file":"get_data.py","line":"142","function":"getData"}`
`logging.googleapis.com/spanId`	`spanId`	L'ID intervallo all'interno traccia associata a la voce di log. Per ulteriori informazioni, vedi `spanId` sulla pagina `LogEntry`.	`"logging.googleapis.com/spanId":"000000000000004a"`
`logging.googleapis.com/trace`	`trace`	Nome risorsa della traccia associati a la voce di log se ce ne sono. Per ulteriori informazioni, consulta `trace` nella pagina `LogEntry`.	`"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a"` Nota: se non scrivi a `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 Esplora log il visualizzatore tracce per raggruppare le voci di log e mostrarle 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 ulteriori informazioni, consulta `traceSampled` nella pagina `LogEntry`.	`"logging.googleapis.com/trace_sampled": false`

Campi correlati al tempo

In generale, le informazioni di tempo relative a una voce di log vengono archiviate nel 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 è costituita da dati strutturati, l'agente di logging utilizza le seguenti regole per cercare informazioni relative al tempo nei campi della voce jsonPayload:

Cerca un campo timestamp che sia un oggetto JSON che includa il parametro seconds e nanos che rappresentano, rispettivamente, un campo numero di secondi dell'epoca UTC e un numero non negativo di secondi frazionari:
```
jsonPayload: {
  ...
  "timestamp": {
    "seconds": CURRENT_SECONDS,
    "nanos": CURRENT_NANOS
  }
}
```
Se la ricerca precedente non riesce, cerca per una coppia di campi timestampSeconds e timestampNanos:
```
jsonPayload: {
  ...
  "timestampSeconds": CURRENT_SECONDS,
  "timestampNanos": CURRENT_NANOS
}
```
Se la ricerca precedente non riesce, cerca un campo time che sia stringa in RFC 3339 formato:
```
jsonPayload: {
  ...
  "time": CURRENT_TIME_RFC3339
}
```

Quando vengono trovate informazioni correlate al tempo, l'agente Logging utilizza queste informazioni. per impostare il valore di LogEntry.timestamp, che non verrà copiato informazioni dal record strutturato all'oggetto LogEntry.jsonPayload.

I campi relativi al tempo che non vengono utilizzati per impostare il valore dell'attributo Il campo LogEntry.timestamp viene copiato dal record strutturato al 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 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 Agente Logging per inviare log aggiuntivi a Logging o per regolare 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 in che modo i log vengono trasformati e importati in Cloud Logging.

Località 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 prima della versione 1-5, la località è: C:\GoogleStackdriverLoggingAgent\fluent.conf
Descrizione: questo file include opzioni di configurazione per controllare lo Comportamento del plug-in di output fluent-plugin-google-cloud.
Esamina il repository di configurazione.

Log di streaming da input aggiuntivi

Puoi personalizzare Agente Logging per inviare log aggiuntivi a Logging aggiungendo configurazioni di input.

Flusso di log non strutturati (testo) tramite 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 è aggiungere le 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 verificare 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) tramite file di log

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

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

Per configurare l'agente Logging per l'importazione di contenuti in formato JSON, segui questi passaggi:

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

Crea un nuovo file di configurazione con l'etichetta 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 è aggiungere la configurazione informazioni 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 verificare 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 valore 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 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 log al in_forward . La documentazione di fluentd contiene ulteriori dettagli su questo strumento.

Per inviare i log tramite il plug-in in_forward fluentd, leggi quanto segue istruzioni:

Esegui il seguente comando sulla VM con l'agente di 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 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 attivare connettori in vari linguaggi 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 delle voci 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 del log sono associate alle risorse monitorate. Per ulteriori informazioni, consulta l'elenco dei tipi di risorse monitorate 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 della mappa è una coppia {`field_name`: `label_name`}. Quando viene rilevato `field_name` (come analizzato dal plug-in di input), alla voce del log viene aggiunta un'etichetta con il `field_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 consentiti all'interno dei nomi dei campi `fluentd`. Per un esempio, consulta Impostare le 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 altrimenti 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:

Sostituzione dinamica di etichette specifiche in una voce strutturata con altre. Per maggiori dettagli, vedi Impostare le etichette nelle voci di log strutturate in questa pagina.
In modo statico, l'etichetta viene associata a qualsiasi occorrenza di un valore. Per maggiori dettagli, consulta Impostare le etichette in modo statico in questa pagina.

Impostazione delle etichette nelle voci di log strutturate

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

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

Supponi di voler tradurre il campo del payload env in un metadato l'etichetta environment. Per farlo, aggiungi quanto segue al plug-in di output configurazione 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 l'etichetta environment con il valore production.

Impostazione delle etichette in modo statico

Se non hai queste informazioni nel payload e vuoi semplicemente aggiungere un etichetta metadati statica denominata environment, aggiungi quanto segue all'output configurazione del plug-in 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, invece di utilizzare una mappa per sostituire un'etichetta con un'altra, utilizziamo una Impostazione labels per collegare 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 ulteriori informazioni su come configurare labels, label_map e altre Impostazioni dell'agente Logging, vai a Impostazione delle 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 filtro più utilizzato è filter_record_transformer. Ti consente di:

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 inoltre di modificare le voci di log. Il plug-in di output fluent-plugin-record-reformer offre funzionalità simili a filter_record_transformer plug-in di filtro, tranne che consente anche di modificare i tag di log. Questo plug-in prevede un maggiore utilizzo delle risorse: ogni volta che viene inserito un tag di log aggiornato, genera una nuova voce di log con il nuovo tag. Tieni presente che il campo tag nella configurazione è obbligatorio. Ti consigliamo inoltre di modificarlo per evitare di entrare in un loop infinito.

Il plug-in di output fluent-plugin-detect-exceptions analizza uno stream di log, con record di log non strutturati (di testo) o in formato JSON, per rilevare tracce dello stack delle 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 singolo messaggio di log combinato. Altrimenti, la voce di log viene inoltrata così com'era.

Definizioni della configurazione avanzata (non predefinita)

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

Opzioni di configurazione relative ai buffer

Le seguenti opzioni di configurazione ti consentono di regolare il meccanismo di buffering interno dell'agente di 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ò trovarsi in memoria o in file reali. Valore consigliato: `buf_file`. Il valore predefinito di `buf_memory` è 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 vengono archiviati i blocchi del buffer. Questo parametro è obbligatorio se `buffer_type` è `file`. Questa configurazione deve essere univoca per evitare una condizione di gara.
`buffer_queue_limit`	int	`64`	Specifica il limite di lunghezza della coda di chunk. Quando la coda del buffer raggiunge questo numero di chunk, il comportamento del buffer è controllato da `buffer_queue_full_action`. Per impostazione predefinita, vengono lanciate eccezioni. Questa opzione, in combinazione con `buffer_chunk_limit`, determina lo spazio su disco massimo impiegato 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`: lancia `BufferQueueLimitError` quando la coda è piena. La modalità di gestione di `BufferQueueLimitError` dipende dai plug-in di input. Ad esempio, il plug-in di input `in_tail` smette di leggere le 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 è ideale per i casi d'uso batch. `fluentd` sconsiglia di utilizzare l'azione di blocco per evitare `BufferQueueLimitError`. Se raggiungi spesso `BufferQueueLimitError`, significa che la capacità della destinazione non è sufficiente per il tuo traffico. 3. `drop_oldest_chunk`: questa modalità elimina i blocchi meno recenti.

Opzioni di configurazione relative ai progetti e alle risorse monitorate

Le seguenti opzioni di configurazione ti consentono di specificare manualmente ad alcuni campi dell'oggetto MonitoredResource. Questi valori vengono raccolti automaticamente dall'agente di logging. Non è consigliabile specificarli manualmente.

Nome della configurazione	Tipo	Predefinito	Descrizione
`project_id`	string	nil	Se specificato, sostituisce il `project_id` che identifica il progetto Google Cloud o AWS sottostante in cui è in esecuzione l'agente di logging.
`zone`	string	nil	Se specificato, sostituisce la zona.
`vm_id`	string	nil	Se specificato, sostituisce l'ID della VM.
`vm_name`	string	nil	Se specificato, 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 del 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 verrà sostituito dalla stringa specificata da `non_utf8_replacement_string`. Se impostato su `false`, qualsiasi carattere non UTF-8 attiverà un errore nel 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 convalidati convertendo qualsiasi tag non stringa in una stringa e sottoponendo a sanificazione tutti i caratteri non UTF-8 o altri caratteri non validi.
`non_utf8_replacement_string`	string	`""`(spazio)	Se il criterio `coerce_to_utf8` viene impostato su `true`, tutti i caratteri non UTF-8 vengono sostituiti dalla stringa specificata qui.

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

Applicazione della configurazione personalizzata dell'agente in corso...

La personalizzazione dell'agente Logging ti consente di aggiungere il tuo fluentd file di configurazione:

Istanza Linux

Copia i file di configurazione nella seguente directory:
```
/etc/google-fluentd/config.d/
```
Lo script di installazione dell'agente di logging compila questa directory con i file di configurazione catch-all predefiniti. Per ulteriori informazioni, consulta Ottenere il codice sorgente dell'agente di 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

Instanza Windows

Copia i file di configurazione nella sottodirectory config.d della directory di installazione dell'agente. Se hai accettato l'installazione predefinita directory, questa directory è:
```
C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
```
Riavvia l'agente eseguendo questi comandi in una riga di comando shell:
```
net stop  StackdriverLogging
net start StackdriverLogging
```

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