Questa pagina fornisce i 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 raccoglitore dati di log fluentd.
L'agente Logging viene fornito con una configurazione predefinita; nella maggior parte
dei casi più comuni, non è necessaria alcuna configurazione aggiuntiva.
Nella configurazione predefinita, l'agente Logging trasmette il flusso dei log, come incluso nell'elenco dei log predefiniti, a Cloud Logging. Puoi configurare l'agente per trasmettere un flusso di log aggiuntivi. Per maggiori dettagli, vedi Personalizzazione della configurazione dell'agente Logging in questa pagina.
L'agente Logging utilizza i plug-in di input fluentd
per recuperare ed eseguire il pull di log eventi da origini esterne, come i file su disco, o per analizzare i record di log in entrata. I plug-in di input sono in bundle con l'agente o possono essere installati separatamente come gemme Ruby; consulta l'elenco dei plug-in in bundle.
L'agente legge i record di log archiviati nei file di log nell'istanza VM tramite il
plug-in in_tail
integrato di fluentd
. Ogni record di log viene convertito in una struttura di voci di log per Cloud Logging. I contenuti di ogni record di log vengono registrati principalmente nel payload delle voci di log, ma queste contengono anche elementi standard come timestamp e severity. L'agente Logging richiede che ogni record di log sia codificato con un tag in formato stringa; tutte le query e tutti i plug-in di output corrispondono a un insieme specifico di tag. Il nome log
di solito è nel formato
projects/[PROJECT-ID]/logs/[TAG]
. Ad esempio, questo nome log include il tag structured-log
:
projects/my-sample-project-12345/logs/structured-log
Il plug-in di output trasforma ogni messaggio strutturato interiorizzato in una voce di log in Cloud Logging. Il payload diventa il testo o JSON.
Le seguenti sezioni di questa pagina trattano in dettaglio la configurazione predefinita.
Definizioni di configurazione predefinite
Le seguenti sezioni descrivono le definizioni di configurazione predefinite per syslog, il plug-in di forwarding, le configurazioni di input per i log delle applicazioni di terze parti, come quelle nell'elenco dei log predefiniti, e il plug-in di output fluentd
di Google Cloud.
Posizione del file di configurazione radice
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 prima della versione 1-5, la località è:
C:\GoogleStackdriverLoggingAgent\fluent.conf
Configurazione SysLog
Posizione 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 | Valore 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'intestazione del file anziché dal basso. Consulta la documentazione dettagliata di fluentd . |
tag |
string | syslog |
Il tag di log per questo input di log. |
Configurazione plug-in di input in_forward
Posizione 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 inputin_forward
ti consente di passare i log tramite un socket TCP.Consulta la documentazione dettagliata di
fluentd
relativa a questo plug-in e al repository di configurazione.
Nome della configurazione | Tipo | Valore predefinito | Descrizione |
---|---|---|---|
port |
int | 24224 |
La porta da monitorare. |
bind |
string | 127.0.0.1 |
L'indirizzo di binding da monitorare. Per impostazione predefinita, sono accettate solo connessioni da localhost. Per aprirlo, è necessario cambiare la configurazione in 0.0.0.0 . |
Configurazione dell'input del log dell'applicazione di terze parti
Località dei file di configurazione:
/etc/google-fluentd/config.d/[APPLICATION_NAME].conf
Descrizione: questa directory include file di configurazione che consentono di specificare i file di log delle applicazioni di terze parti come input di log. Ogni file, eccetto
syslog.conf
eforward.conf
, rappresenta un'applicazione (ad es.apache.conf
per l'applicazione Apache).Esamina il repository di configurazione.
Nome della configurazione | Tipo | Valore predefinito | Descrizione |
---|---|---|---|
format 1 |
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 ",". * e il formato strftime possono essere inclusi per aggiungere/rimuovere il file di visualizzazione in modo dinamico. 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. Leggi 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. |
1 Se utilizzi la stanza <parse>
, specifica il formato del 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
- Linux:
Descrizione: questo file include opzioni di configurazione per controllare il comportamento del plug-in di output Google Cloud
fluentd
.Vai al repository di configurazione.
Nome della configurazione | Tipo | Valore 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 inviati a una coda di blocchi. Questa configurazione imposta il limite delle dimensioni di ogni blocco. Per impostazione predefinita, impostiamo il limite di blocchi in modo prudente per evitare di superare la dimensione consigliata del blocco di 5 MB per richiesta di scrittura nell'API Logging. Le voci di log nella richiesta API possono essere da cinque a otto volte più grandi della dimensione log originale con tutti i metadati aggiuntivi allegati. Un blocco buffer viene svuotato se viene soddisfatta una delle due condizioni: 1. Calcio d'azione di flush_interval . 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 inviati a una coda di blocchi. La configurazione imposta il tempo che deve trascorrere prima dello svuotamento del buffer di un blocco. Un blocco buffer viene svuotato se viene soddisfatta una delle due condizioni: 1. Calcio d'azione di flush_interval . 2. La dimensione del buffer raggiunge buffer_chunk_limit . |
disable_retry_limit |
bool | false |
Applica un limite al numero di nuovi tentativi per lo svuotamento dei blocchi di buffer non riusciti. Esamina le specifiche dettagliate in retry_limit , retry_wait e max_retry_wait . |
retry_limit |
int | 3 |
Quando non è possibile eliminare un blocco di buffer, fluentd per impostazione predefinita 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 eliminare un blocco di buffer, 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 successivo (20 s, 40 s...) fino a quando non viene raggiunto il valore retry_ limit o max_retry_wait . |
max_retry_wait |
int | 300 |
Quando non è possibile eliminare un blocco di buffer, fluentd per impostazione predefinita riprova in un secondo momento. L'intervallo di attesa raddoppia a ogni nuovo tentativo successivo (20, 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 dei 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 è generalmente 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 viene 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 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 viene impostata su true , la traccia viene riformattata se il valore del campo payload strutturato logging.googleapis.com/trace corrisponde al formato traceId ResourceTrace. Puoi trovare i dettagli della formattazione automatica in Campi speciali nei payload strutturati in questa pagina. |
Configurazione del monitoraggio
Telemetria del plug-in di output
L'opzione enable_monitoring
consente di stabilire se il plug-in di output fluentd
di Google Cloud raccoglie i propri dati di telemetria interna. Se viene impostato su true
, l'agente Logging tiene traccia del numero di voci di log che è necessario inviare a Cloud Logging e del numero effettivo di voci di log importate correttamente da Cloud Logging. Se il criterio viene impostato su false
, il plug-in di output non raccoglie metriche.
L'opzione monitoring_type
controlla in che modo questa telemetria viene esposta
dall'agente. Vedi l'elenco delle metriche 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 la configurazione del plug-in prometheus e prometheus_monitor per i dettagli su come personalizzarla). Sulle VM di Compute Engine, per poter scrivere le metriche nell'API Monitoring, è necessario installare ed eseguire 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 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 etichettaversion
: tempo di attività dell'agente Logging.agent.googleapis.com/agent/log_entry_count
con etichettaresponse_code
: numero di voci di log scritte dall'agente Logging.agent.googleapis.com/agent/log_entry_retry_count
con un'etichettaresponse_code
: numero di voci di log scritte dall'agente Logging.agent.googleapis.com/agent/request_count
con etichettaresponse_code
: numero di richieste API da parte dell'agente Logging.
Queste metriche sono descritte in maggiore dettaglio nella pagina Metriche degli agenti.
Inoltre, il plug-in di output mostra le seguenti metriche di Prometheus in modalità prometheus
:
uptime
con etichettaversion
: tempo di attività dell'agente Logging.stackdriver_successful_requests_count
con etichettegrpc
ecode
: il numero di richieste riuscite all'API Logging.stackdriver_failed_requests_count
con etichettegrpc
ecode
: il numero di richieste all'API Logging non riuscite, suddivise in base al codice di errore.stackdriver_ingested_entries_count
con etichettegrpc
ecode
: il numero di voci di log importate dall'API Logging.stackdriver_dropped_entries_count
con etichettegrpc
ecode
: il numero di voci di log rifiutate dall'API Logging.stackdriver_retried_entries_count
con etichettegrpc
ecode
: il numero di voci di log che non è stato possibile importare da parte del plug-in di output Google Cloudfluentd
a causa di un errore temporaneo e che sono state sottoposte a un nuovo tentativo.
Configurazione del 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 dei plug-in
prometheus
eprometheus_monitor
. Il plug-inprometheus_monitor
monitora l'infrastruttura di base di Fluentd. Il plug-inprometheus
espone le metriche, comprese quelle del plug-inprometheus_monitor
e quelle del plug-ingoogle_cloud
in alto, tramite una porta locale in formato Prometheus. Ulteriori dettagli sono disponibili 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 interrompere 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 in corso...
La maggior parte dei log supportati nella configurazione predefinita dell'agente Logging proviene da file di log e vengono importati 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 i log strutturati e li importa come payload strutturati (JSON) nelle voci di log. Per maggiori dettagli, consulta la pagina relativa ai record di log strutturati (JSON) per i flussi di dati 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
abilitata viene sempre importato come jsonPayload
.
Puoi personalizzare la configurazione degli agenti per supportare l'importazione di log strutturati da risorse aggiuntive. Per maggiori dettagli, consulta Record di log strutturati per i flussi di dati (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 tutte le chiavi corrispondenti alla seguente tabella nel campo corrispondente dell'oggetto LogEntry. In caso contrario, la chiave diventa parte del campo LogEntry.jsonPayload
. Questo comportamento consente di impostare campi specifici nell'oggetto LogEntry
, che è quanto viene scritto nell'API Logging.
Ad esempio, se il record del log strutturato contiene una chiave di severity
, l'agente Logging compila il campo LogEntry.severity
.
Campo log JSON |
Campo LogEntry
|
Funzione 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 sulla 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 ad ambienti di logging gestiti come Google Kubernetes Engine. Se la voce di log contiene un'analisi dello stack di eccezioni, è necessario impostare l'analisi dello stack di eccezioni in questo campo di log JSON message , in modo che l'analisi dello stack di eccezioni possa essere analizzata e salvata in Error Reporting. |
log
(solo
versione precedente di Google Kubernetes Engine) |
textPayload
|
Si applica solo alla versione precedente di Google Kubernetes Engine: se, dopo lo spostamento di campi per scopi speciali, rimane solo un campo log , questo campo viene salvato come textPayload . |
|
httpRequest
|
httpRequest
|
Un record strutturato nel formato
del campo LogEntry
HttpRequest . |
"httpRequest":{"requestMethod":"GET"}
|
di campi temporali | timestamp
|
Per ulteriori informazioni, consulta la sezione Campi correlati al tempo. | "time":"2020-10-12T07:20:50.52Z"
|
logging.googleapis.com/insertId
|
insertId
|
Per ulteriori informazioni, 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 maggiori 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 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 all'eventuale voce di log.
Per ulteriori informazioni, consulta LogEntrySourceLocation nella pagina LogEntry . |
"logging.googleapis.com/sourceLocation":
{"file":"get_data.py","line":"142","function":"getData"}
|
logging.googleapis.com/spanId
|
spanId
|
L'ID intervallo all'interno della traccia associata alla voce di log.
Per ulteriori informazioni, consulta spanId nella pagina LogEntry . |
"logging.googleapis.com/spanId":"000000000000004a"
|
logging.googleapis.com/trace
|
trace
|
Nome di risorsa della traccia associata all'eventuale voce di log.
Per ulteriori informazioni, consulta trace nella pagina LogEntry .
|
"logging.googleapis.com/trace":"projects/my-projectid/traces/0679686673a" Nota: se non scrivi in 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 e
dal visualizzatore di tracce 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 avrà 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 relative al tempo su una voce di log sono 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 è costituita da dati strutturati, l'agente 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 i campiseconds
enanos
, che rappresentano rispettivamente un numero firmato di secondi 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
etimestampNanos
:jsonPayload: { ... "timestampSeconds": CURRENT_SECONDS, "timestampNanos": CURRENT_NANOS }
Se la ricerca precedente ha esito negativo, cerca un campo
time
che corrisponde a una stringa nel 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 correlati al tempo che non vengono utilizzati per impostare il valore del campo LogEntry.timestamp
vengono copiati dal record strutturato all'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 degli agenti
Oltre all'elenco di log predefiniti che l'agente Logging trasmette per impostazione predefinita, puoi personalizzare l'agente Logging in modo che invii log aggiuntivi a Logging o per modificare le impostazioni dell'agente aggiungendo configurazioni di input.
Le definizioni della 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.
Posizione 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
- Linux:
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 in modo che invii log aggiuntivi a Logging aggiungendo configurazioni di input.
Streaming di log non strutturati (testo) tramite file di log
Crea un file di log dal prompt dei comandi di Linux:
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
In alternativa alla creazione di un nuovo file, puoi 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 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 dei log strutturati (JSON) tramite i file di log
Puoi configurare l'agente Logging in modo che richieda la strutturazione di ogni voce di log per determinati input di log. Puoi anche personalizzare l'agente Logging per importare contenuti in formato JSON da un file di log. Se l'agente è configurato per importare contenuti JSON, l'input deve essere formattato in modo che ogni oggetto JSON sia su una nuova riga:
{"name" : "zeeshan", "age" : 28} {"name" : "reeba", "age" : 15}
Per configurare l'agente Logging per l'importazione di contenuti in formato JSON:
Crea un file di log dal prompt dei comandi di Linux:
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
In alternativa alla creazione di un nuovo file, puoi 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 '{"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 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 in base al tipo di risorsa e a un valore logName pari a
structured-log
.
Per ulteriori opzioni sulla personalizzazione del formato di input di log per le applicazioni di terze parti più comuni, consulta Formati di log comuni e come analizzarli.
Streaming dei log strutturati (JSON) tramite il plug-in in_forward
Inoltre, puoi inviare i log tramite il plug-in in_forward
fluentd
.
fluentd-cat
è uno strumento integrato che consente di inviare facilmente i log al plug-in in_forward
. La documentazione di fluentd
contiene ulteriori dettagli su questo strumento.
Per inviare i log tramite il plug-in in_forward
fluentd
, leggi le seguenti istruzioni:
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
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 dei 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 ulteriori
informazioni, consulta la documentazione di fluentd
.
Questi connettori sono creati sulla base del plug-in in_forward
.
Impostazione delle etichette voce di log
Le seguenti opzioni di configurazione consentono di eseguire l'override delle etichette LogEntry e delle etichette 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 | Valore predefinito | Descrizione |
---|---|---|---|
label_map |
cancelletto | 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 rilevata field_name (come analizzata 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 maggiore flessibilità nella specifica dei nomi delle etichette, compresa la possibilità di utilizzare caratteri non consentiti nei nomi dei campi fluentd . Per un esempio, vedi Impostare le etichette nelle voci di log strutturati. |
labels |
cancelletto | nil | labels (specificato come oggetto JSON) è un insieme di etichette personalizzate fornite al momento della configurazione. Consente di inserire ulteriori informazioni ambientali 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 etichette diverse. Per maggiori dettagli, vai a Impostare le etichette nelle voci di log strutturati in questa pagina.
- L'applicazione di un'etichetta a qualsiasi occorrenza di un valore in modo statico. Per maggiori dettagli, vai a Impostare le etichette in modo statico in questa pagina.
Impostazione delle etichette nelle voci di log strutturati
Supponi di aver scritto un payload per una voce di log strutturata come il seguente:
{ "message": "This is a log message", "timestamp": "Aug 10 20:07:00", "env": "production" }
Supponiamo di voler tradurre il campo del payload env
in un'etichetta
dei metadati environment
. A questo scopo, 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
in questo caso sostituisce l'etichetta env
nel payload con
environment
, pertanto la voce di log risultante avrà un'etichetta environment
con
il valore production
.
Impostazione delle etichette in modo statico
Se non disponi di 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 associare 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
Impostare le etichette delle voci di log su 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 permette 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 anche di modificare le voci di log.
Il plug-in di output fluent-plugin-record-reformer
offre funzionalità simili al plug-in del filtro filter_record_transformer
, ad eccezione del fatto che consente anche di modificare i tag di log.
Con questo plug-in è previsto un maggiore utilizzo delle risorse: ogni volta che un tag di log viene aggiornato, verrà 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 di attacco.
Il plug-in di output fluent-plugin-detect-exceptions
analizza un flusso di log, in record di log non strutturati (testo) o in formato JSON, per rilevare le 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 singolo messaggio di log combinato. In caso contrario, la voce di log viene inoltrata così com'era.
Definizioni di configurazione avanzate (non predefinite)
Se vuoi personalizzare la configurazione dell'agente Logging, oltre alla configurazione predefinita, continua a leggere questa pagina.
Opzioni di configurazione relative al buffer
Le opzioni di configurazione seguenti consentono di regolare il meccanismo di buffering interno dell'agente Logging.
Nome della configurazione | Tipo | Valore predefinito | Descrizione |
---|---|---|---|
buffer_type |
string | buf_memory |
I record che non possono essere scritti nell'API Logging abbastanza velocemente vengono inviati 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 permanente. 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 di 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 dei blocchi. Quando la coda del buffer raggiunge questo numero di blocchi, 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 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 : genera 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 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 completa del buffer. Questa azione è utile per casi d'uso di tipo batch. fluentd sconsiglia di utilizzare l'azione di blocco per evitare BufferQueueLimitError . Se premi spesso BufferQueueLimitError , significa che la capacità della tua destinazione non è sufficiente per il tuo traffico. 3. drop_oldest_chunk : questa modalità elimina i blocchi meno recenti. |
Opzioni di configurazione relative al progetto e alle risorsa monitorata
Le seguenti opzioni di configurazione 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 | Valore predefinito | Descrizione |
---|---|---|---|
project_id |
string | nil | Se specificato, sostituisce il valore project_id che identifica il progetto Google Cloud o AWS sottostante in cui è in esecuzione l'agente Logging. |
zone |
string | nil | Se specificato, sostituisce la zona. |
vm_id |
string | nil | Se specificato, sostituisce l'ID 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 | Valore predefinito | Descrizione |
---|---|---|---|
detect_json 1 |
bool | false |
Indica se tentare di rilevare se il record di log è una voce di log di testo con contenuto JSON che deve essere analizzato. Se questa opzione è true e una voce di log non strutturata (di testo) viene rilevata in formato JSON, viene analizzata e inviata come payload strutturato (JSON). |
coerce_to_utf8 |
bool | true |
Indica se consentire i caratteri non UTF-8 nei log utente. Se il criterio viene impostato su true , i caratteri non UTF-8 vengono sostituiti 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 |
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 | "" (spazio) |
Se il criterio coerce_to_utf8 viene impostato su true , i caratteri non UTF-8 vengono sostituiti dalla stringa specificata qui. |
1Questa funzionalità è abilitata per impostazione predefinita nelle istanze VM in esecuzione nell'ambiente flessibile di App Engine e in Google Kubernetes Engine.
Applicazione della configurazione personalizzata dell'agente in corso...
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 maggiori informazioni, 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 sarà:C:\Program Files (x86)\Stackdriver\LoggingAgent\config.d\
Riavvia l'agente eseguendo i comandi seguenti 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 dei file di configurazione di fluentd.