Introduzione

Utilizza il software di raccolta dati open source Fluentd per raccogliere i dati di log dalla tua origine. Installare il plugin di output di Log Analytics OCI per instradare i dati di log raccolti a Oracle Cloud Log Analytics.

Nota: Oracle consiglia di utilizzare gli Oracle Cloud Management Agent per avere la migliore esperienza di inclusione dei dati di log in Oracle Cloud Log Analytics. Tuttavia, se questa opzione non è possibile per il tuo caso d'uso, utilizza solo il plugin di output di OCI Log Analytics per Fluentd.

In questa esercitazione viene utilizzata una configurazione Fluentd basata sul package rpm td-agent installato su Oracle Linux, ma i passi richiesti potrebbero essere simili per altre distribuzioni di Fluentd.

Fluentd ha componenti che lavorano insieme per raccogliere i dati di log dalle fonti di input, trasformare i log e instradare i dati di log all'output desiderato. È possibile installare e configurare il plugin di output per Fluentd per includere i log da varie origini in Oracle Cloud Log Analytics.

Descrizione dell'immagine fluentd_plugin_overview.png

Obiettivi

  • Scopri come installare il plugin di output Log Analytics OCI fornito da Oracle per includere i log dall'origine.
  • Creare la configurazione Fluentd per stabilire la raccolta di log dall'origine a Log Analytics.

Eseguire la migrazione del plugin di output di OCI Log Analytics dalla versione 1.x alla 2.x

Se sei un nuovo utente del plugin di output di OCI Log Analytics e devi ancora scaricarlo e installarlo, salta questa sezione e vai a Prerequisiti. Se è stato installato il plugin versione 1.x utilizzando il file fluent-plugin-oci-logging-analytics-1.0.0.gem, tenere presente che è necessario eseguire la migrazione al plugin versione 2.x.

I seguenti parametri di configurazione vengono rinominati in versione 2.x:
1.x 2.x
global_metadata oci_la_global_metadata
metadati oci_la_metadata
entityId oci_la_entity_id
entityType oci_la_entity_type
logSourceName oci_la_log_source_name
logPath oci_la_log_path
logGroupId oci_la_log_group_id
  • È stato aggiunto il supporto per la rimozione automatica dei log del plugin di output di OCI Log Analytics.
  • Il parametro plugin_log_rotation non è più valido. In alternativa, utilizzare i parametri plugin_log_file_size e plugin_log_file_count insieme per eseguire la stessa azione.
  • Installare il plugin versione 2.x utilizzando il comando disponibile nella sezione Install the Output Plugin.

Esegui prerequisiti

Creare il file di configurazione Fluentd

Per configurare Fluentd per instradare i dati di log a Oracle Cloud Log Analytics, modificare il file di configurazione fornito da Fluentd o td-agent e fornire le informazioni relative a Oracle Cloud Log Analytics e ad altre personalizzazioni.

La configurazione del plugin di output Fluentd sarà nel seguente formato:

<match pattern>
@type oci-logging-analytics
 namespace                   <YOUR_OCI_TENANCY_NAMESPACE>

# Auth config file details
 config_file_location        ~/.oci/config 
 profile_name                DEFAULT

# When there is no credentials for proxy
 http_proxy                  "#{ENV['HTTP_PROXY']}"

# To provide proxy credentials
 proxy_ip                    <IP>
 proxy_port                  <port>
 proxy_username              <user>
 proxy_password              <password>

# Configuration for plugin (oci-logging-analytics) generated logs
 plugin_log_location       "#{ENV['FLUENT_OCI_LOG_LOCATION'] || '/var/log'}" 
 plugin_log_level          "#{ENV['FLUENT_OCI_LOG_LEVEL'] || 'info'}"
 plugin_log_rotation       "#{ENV['FLUENT_OCI_LOG_ROTATION'] || 'daily'}"  **(DEPRECATED)**
 plugin_log_file_size      "#{ENV['FLUENT_OCI_LOG_AGE'] || '1MB'}"
 plugin_log_file_count     "#{ENV['FLUENT_OCI_LOG_AGE'] || '10'}"

# Buffer Configuration
 <buffer>
       @type file
       path                                "#{ENV['FLUENT_OCI_BUFFER_PATH'] || '/var/log'}"
       flush_thread_count                  "#{ENV['FLUENT_OCI_BUFFER_FLUSH_THREAD_COUNT'] || '10'}"
       retry_wait                          "#{ENV['FLUENT_OCI_BUFFER_RETRY_WAIT'] || '2'}"                     #seconds
       retry_max_times                     "#{ENV['FLUENT_OCI_BUFFER_RETRY_MAX_TIMES'] || '10'}"
       retry_exponential_backoff_base      "#{ENV['FLUENT_OCI_BUFFER_RETRY_EXPONENTIAL_BACKOFF_BASE'] || '2'}" #seconds
       retry_forever                       true
       overflow_action                     block
       disable_chunk_backup                true
 </buffer>
	</match>

Si consiglia di configurare un plugin secondario che verrà utilizzato da Fluentd per eseguire il dump dei dati di backup quando il plugin di output continua a non riuscire a scrivere i chunk del buffer e supera la soglia di timeout per i nuovi tentativi. Inoltre, per gli errori irreversibili, Fluentd interromperà immediatamente il chunk e lo sposterà nella directory secondaria o di backup. Consultare Documentazione fluentd: output secondario.

Parametri di configurazione plugin di output

Fornire i valori appropriati ai seguenti parametri nel file di configurazione Fluentd:

Parametro configurazione Descrizione
namespace (parametro obbligatorio) Spazio di nomi tenancy OCI in cui caricare i dati di log raccolti
config_file_location Posizione del file di configurazione contenente i dettagli di autenticazione OCI
profile_name Nome profilo configurazione OCI da utilizzare dal file di configurazione
http_proxy Proxy senza credenziali. Esempio: www.proxy.com:80
proxy_ip Dettagli IP proxy quando sono necessarie le credenziali. Esempio: www.proxy.com
proxy_port Dettagli della porta proxy quando sono necessarie le credenziali. Esempio: 80
proxy_username Dettagli nome utente proxy
proxy_password Dettagli della password proxy quando sono richieste le credenziali
plugin_log_location Percorso file per il plugin di output per scrivere i propri log. Assicurarsi che il percorso esista e sia accessibile. Valore predefinito: directory di lavoro.
plugin_log_level Livello di log del plugin di output: DEBUG < INFO < WARN < ERROR < FATAL < UNKNOWN. Valore predefinito: INFO.
plugin_log_rotation (RECATO) Frequenza di rotazione del file di log del plugin di output: giornaliera, settimanale o mensile. Valore predefinito: giornaliero.
plugin_log_file_size La dimensione massima del file di log in corrispondenza della quale deve essere ruotato il file di log.' (1 KB, 1 MB e così via). Valore predefinito: 1MB.
plugin_log_file_count Il numero di file di log archiviati/rotati da conservare (più di 0). Valore predefinito: 10.

Se non si specificano i parametri config_file_location e profile_name per i nodi OCI Compute, viene utilizzata l'autenticazione basata su instance_principal.

Parametri di configurazione del buffer

Nello stesso file di configurazione modificato nella sezione precedente, modificare la sezione del buffer e fornire le seguenti informazioni obbligatorie:

Parametro obbligatorio Descrizione
@type Specifica il plugin da utilizzare come backend. Immettere il file.
percorso Percorso in cui vengono memorizzati i file buffer. Assicurarsi che il percorso esista e sia accessibile.

I seguenti parametri facoltativi possono essere inclusi nel blocco buffer:

Parametro facoltativo Valore predefinito Descrizione
flush_thread_count 1 Numero di thread da svuotare/scrivere in parallelo.
retry_wait 1s Attendere alcuni secondi prima del successivo tentativo di svuotamento.
retry_max_times none Questo campo è obbligatorio solo se il campo retry_forever è false.
retry_exponential_backoff_base 2 Attendere in secondi prima del successivo fattore costante di backoff esponenziale.
retry_forever false Se true, il plugin ignorerà l'opzione retry_max_times e ritenterà di eseguire il flushing per sempre.
overflow_action throw_exception Valori possibili: throw_exception / blocco / drop_oldest_chunk. Valore consigliato: blocco.
disable_chunk_backup false Se specificato, false, i chunk non recuperabili nella directory di backup verranno eliminati.
chunk_limit_size 8MB La dimensione massima di ogni pezzo. Gli eventi saranno scritti in pezzi fino a quando le dimensioni dei pezzi diventeranno così grandi. Nota: indipendentemente dal valore specificato, il plugin di output di Log Analytics attualmente imposta il valore predefinito su 1 MB.
total_limit_size 64GB (per file) Una volta che la dimensione totale del buffer memorizzato ha raggiunto questa soglia, tutte le operazioni di aggiunta non riusciranno con un errore (e i dati andranno persi).
flush_interval 60s Frequenza di svuotamento dei chunk nel plugin di output.

Per informazioni dettagliate sui possibili valori dei parametri, vedere Documentazione di Fluentd: Plugin buffer.

Verificare il formato degli eventi di log in entrata

Gli eventi di log in entrata devono essere in un formato specifico in modo che il plugin Fluentd fornito da Oracle possa elaborare i dati di log, eseguirne il chunk e trasferirli in Oracle Cloud Log Analytics.

Visualizzare la configurazione di esempio da utilizzare per il monitoraggio dei file di log syslog, apache e kafka in Configurazione di input di esempio.

Configurazione plugin origine/input

Configurazione di origine di esempio per i log syslog:

<source>
  @type tail
  @id in_tail_syslog
  multiline_flush_interval 5s
  path /var/log/messages*
  pos_file /var/log/messages*.log.pos
  read_from_head true
  path_key tailed_path
  tag oci.syslog
  <parse>
    @type json
  </parse>
</source>

Per definire il blocco di origine sono obbligatori i seguenti parametri:

  • @type: il tipo di plugin di input. Utilizzare tail per il consumo degli eventi da un file locale. Gli altri valori possibili possono essere http e forward.

  • percorso: il percorso dei file di origine.

  • tag: la tag che verrà utilizzata dal plugin Fluentd di Oracle per filtrare gli eventi di log che devono essere utilizzati da Log Analytics. Assicurarsi di utilizzare il prefisso oci, ad esempio oci.syslog.

  • Direttiva di analisi: si consiglia di non definire la direttiva di analisi nel file di configurazione. Conservare il valore <parse> @type none </parse>. In alternativa, è possibile utilizzare i parser e le origini definiti da Oracle forniti da Log Analytics o creare parser e origini personali in Log Analytics. Per i log con wrapper json, utilizzare la direttiva di analisi <parse> @type json </parse>. Sostituire il campo del messaggio nel filtro record_transformer con il valore ${record["log"]}.

    Nota:

    • Si consiglia di non utilizzare alcun parser Fluentd. Inviare invece i log a Log Analytics nel modulo originale. La direttiva parse deve avere la forma seguente:

      <parse>
    @type none
</parse>

    • Tuttavia, in caso di voci di log su più righe, utilizzare il tipo di parser su più righe per inviare più righe di un log come singolo record. Ad esempio:

      <parse>
    @type multiline
    format_firstline /^\S+\s+\d{1,2}\s+\d{1,2}:\d{1,2}:\d{1,2}\s+/
    format1 /^(?<message>.*)/
</parse>

    • Per i log originali avvolti dal wrapper json in cui una delle chiavi nelle coppie chiave-valore è log, è consigliabile utilizzare la seguente direttiva di analisi:

      <parse>
    @type json
</parse>

    Sostituire il campo message nel filtro record_transformer con message ${record["log"]}. Ad esempio, nel blocco di filtro seguente per i log kafka, il contenuto del log viene memorizzato nel valore del log della chiave sottoposto a wrapping in un json.

    ```
<filter oci.kafka>
@type record_transformer
enable_ruby true
<record>
    oci_la_metadata KEY_VALUE_PAIRS
    oci_la_entity_id LOGGING_ANALYTICS_ENTITY_OCID              # If same across sources. Else keep this in individual filters
    oci_la_entity_type LOGGING_ANALYTICS_ENTITY_TYPE            # If same across sources. Else keep this in individual filters
    oci_la_log_source_name LOGGING_ANALYTICS_SOURCENAME
    oci_la_log_group_id LOGGING_ANALYTICS_LOGGROUP_OCID
    oci_la_log_path "${record['tailed_path']}"
    message ${record["log"]}                            # Will assign the 'log' key value from json wrapped message to 'message' field
    tag ${tag}
</record>
</filter>
```

Nel blocco di origine è possibile includere i parametri facoltativi riportati di seguito.

  • multiline_flush_interval: impostare questo valore solo per i log su più righe per assicurarsi che tutti i log vengano utilizzati da Log Analytics. Se il valore non è impostato per i log su più righe, Fluentd rimarrà in modalità di attesa per il batch di record successivo. Per impostazione predefinita, questo parametro è disabilitato.
  • pos_file: utilizzare questo parametro per specificare il file in cui Fluentd gestisce il record della posizione dell'ultima lettura.

Per informazioni su altri parametri, vedere Documentazione fluentd: tail.

Configurazione filtro

Utilizzare questi parametri per elencare le risorse di Log Analytics da utilizzare per elaborare i log.

Per assicurarsi che i log dell'origine di input possano essere elaborati dal plugin di output fornito da Oracle, verificare che gli eventi del log di input siano conformi al formato prescritto, ad esempio configurando il plugin di filtro record_transformer per modificare il formato di conseguenza.

Suggerimento: la configurazione del plugin di filtro record_transformer è solo uno dei modi per includere i parametri richiesti negli eventi in entrata. Per ulteriori informazioni su altri metodi, consultare Documentazione Fluentd.

Configurazione filtro di esempio:

    <filter oci.kafka>
    @type record_transformer
    enable_ruby true
    <record>
        oci_la_metadata KEY_VALUE_PAIRS
        oci_la_entity_id LOGGING_ANALYTICS_ENTITY_OCID              # If same across sources. Else keep this in individual filters
        oci_la_entity_type LOGGING_ANALYTICS_ENTITY_TYPE            # If same across sources. Else keep this in individual filters
        oci_la_log_source_name LOGGING_ANALYTICS_SOURCENAME
        oci_la_log_group_id LOGGING_ANALYTICS_LOGGROUP_OCID
        oci_la_log_path "${record['tailed_path']}"
        message ${record["log"]}                            # Will assign the 'log' key value from json wrapped message to 'message' field
        tag ${tag}
    </record>
    </filter>`

Fornire le seguenti informazioni obbligatorie nel blocco di filtro:

  • <filter oci.kafka>: parametro per definire un blocco di filtro per la tag specificata nel blocco di origine.
  • @type record_transformer: il plugin trasformatore di record trasforma il record di log originale in un form che può essere utilizzato dal plugin di output di OCI Log Analytics.
  • enable_ruby: consente l'uso dell'espressione Ruby all'interno di ${...}.
  • oci_la_entity_id: l'OCID dell'entità Log Analytics creata in precedenza nel task dei prerequisiti per mappare l'host.
  • oci_la_entity_type: il tipo di entità dell'entità Log Analytics creata in precedenza nel task dei prerequisiti.
  • oci_la_log_source_name: l'origine di Log Analytics da utilizzare per elaborare i record di log.
  • oci_la_log_path: specificare la posizione originale dei file di log. Se il valore di oci_la_log_path non è specificato o non è valido, procedere come segue.
    • se la tag è disponibile, viene utilizzata come oci_la_log_path
    • se tag non è disponibile, oci_la_log_path è impostato su UNDEFINED
  • oci_la_log_group_id: OCID del gruppo di log di Log Analytics in cui devono essere memorizzati i log.

Facoltativamente, è possibile fornire i seguenti parametri aggiuntivi nel blocco di filtro:

  • <filter oci.**>: utilizzare questo filtro per fornire le informazioni di configurazione applicabili a tutte le origini. Se si utilizza questo filtro, assicurarsi che sia prima nell'ordine di esecuzione tra i filtri. Se la stessa chiave viene specificata sia nel filtro globale che nel singolo filtro di origine, il valore del filtro a livello di origine sostituirà il filtro globale. Si consiglia di utilizzare oci come prefisso per tutte le tag.
  • oci_la_global_metadata: utilizzare questo parametro per specificare metadati aggiuntivi insieme al contenuto di log originale in Log Analytics nel formato 'key1': 'value1', 'key2': 'value2'. Qui, Chiave è il campo di Log Analytics che deve essere già definito prima di specificarlo qui. I metadati globali vengono applicati a tutti i file di log.
  • oci_la_metadata: utilizzare questo parametro per definire metadati aggiuntivi insieme al contenuto di log originale in Log Analytics nel formato 'key1': 'value1', 'key2': 'value2'. Qui, Chiave è il campo di Log Analytics che deve essere già definito prima di specificarlo qui.
  • tag: utilizzare questo parametro per allegare una tag al messaggio per uso interno. Specificare nel formato tag ${tag}.
  • messaggio ${record["log"]}: includere questo parametro per i log sottoposti a wrapper json in cui il messaggio di log originale è il valore dell'attributo log all'interno di json.

Esempio di configurazioni che è possibile utilizzare per monitorare i log riportati di seguito.

Installare il plugin di output

Utilizzare il file gem fornito da Oracle per l'installazione del plugin di output di OCI Log Analytics. I passaggi di questa sezione riguardano la configurazione Fluentd basata sul package rpm td-agent installato su Oracle Linux.

  1. Installare il plugin di output eseguendo il seguente comando:

    gem install fluent-plugin-oci-logging-analytics

Per ulteriori informazioni, vedere Plugin di output Fluentd per la spedizione di log/eventi a OCI Log Analytics su RubyGems: https://rubygems.org/gems/fluent-plugin-oci-logging-analytics.

  1. Systemd avvia td-agent con l'utente td-agent. Consente all'utente td-agent di accedere ai file e alle cartelle OCI. Per eseguire td-agent come servizio, eseguire il comando chown o chgrp per le cartelle del plugin di output di Log Analytics OCI e il file pem .OCI, ad esempio chown td-agent [FILE].

  2. Per iniziare a raccogliere i log in Oracle Cloud Log Analytics, eseguire td-agent:

    TZ=utc /etc/init.d/td-agent start

    È possibile utilizzare il file di log /var/log/td-agent/td-agent.log per eseguire il debug in caso di problemi durante la raccolta dei log o durante l'impostazione.

    Per arrestare td-agent in qualsiasi punto, eseguire il comando seguente:

    TZ=utc /etc/init.d/td-agent stop

Avvio della visualizzazione dei log in Log Analytics

Andare a Log Explorer e utilizzare il pannello Visualizza di Oracle Cloud Log Analytics per visualizzare i dati di log in un modulo che consente di comprendere e analizzare meglio i dati. In base a ciò che si desidera ottenere con il data set, è possibile selezionare il tipo di visualizzazione più adatto all'applicazione.

Dopo aver creato ed eseguito una query di ricerca, è possibile salvare e condividere le ricerche di log come widget per un ulteriore riutilizzo.

È possibile creare dashboard personalizzati nella pagina Dashboard aggiungendo i widget definiti da Oracle o i widget personalizzati creati.

Monitorare fluente utilizzando Prometheus

È possibile facoltativamente monitorare Fluentd utilizzando Prometheus. Per i passi da eseguire per esporre le metriche riportate di seguito e altre emesse da Fluentd a Prometheus, vedere Documentazione di Fluentd: Monitoraggio di Prometheus. Se si desidera monitorare solo Fluentd di base e queste metriche, saltare i passi Passo 1: conteggio dei record in entrata per plugin di filtro Prometheus e Passo 2: conteggio dei record in uscita per plugin di output Prometheus nella documentazione Fluentd di riferimento.

Il plugin Fluentd emette le seguenti metriche in formato Prometheus, che fornisce approfondimenti sui dati raccolti ed elaborati dal plugin:

Metric Name: oci_la_fluentd_output_plugin_records_received 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of records received by the OCI Log Analytics Fluentd output plugin.
Type : Gauge

Metric Name: oci_la_fluentd_output_plugin_records_valid 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of valid records received by the OCI Log Analytics Fluentd output plugin.
Type : Gauge 

Metric Name: oci_la_fluentd_output_plugin_records_invalid 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set,:reason]
Description: Number of invalid records received by the OCI Log Analytics Fluentd output plugin. 
Type : Gauge

Metric Name: oci_la_fluentd_output_plugin_records_post_error 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set,:error_code, :reason]
Description: Number of records failed posting to OCI Log Analytics by the Fluentd output plugin.
Type : Gauge
    
Metric Name: oci_la_fluentd_output_plugin_records_post_success 
labels: [:tag,:oci_la_log_group_id,:oci_la_log_source_name,:oci_la_log_set]
Description: Number of records posted by the OCI Log Analytics Fluentd output plugin. 
Type : Gauge  

Metric Name: oci_la_fluentd_output_plugin_chunk_time_to_receive
labels: [:tag]
Description: Average time taken by Fluentd to deliver the collected records from Input plugin to OCI Log Analytics output plugin.
Type : Histogram  

Metric Name: oci_la_fluentd_output_plugin_chunk_time_to_post 
labels: [:oci_la_log_group_id]
Description: Average time taken for posting the received records to OCI Log Analytics by the Fluentd output plugin.
Type : Histogram

Per saperne di più

Altre risorse di apprendimento

Esplora altri tutorial su Oracle Learn o accedi a più contenuti di formazione gratuiti sul canale YouTube di Oracle Learning. Inoltre, visita Oracle Education per diventare un Oracle Learning Explorer.

Per la documentazione del prodotto, visitare Oracle Help Center.