Supporto di log multilinea per Agent di registrazione in ambienti orchestrati

Gli errori e le tracce di stack possono estendersi su più righe e ogni riga viene inviata come voce di registro separata. Per supportare l'ingestione di log multilinea da parte di IBM® Cloud Logs da applicazioni, come Java o Python, in esecuzione in ambienti orchestrati, come Red Hat OpenShift on IBM Cloud o IBM Cloud Kubernetes Service, è necessario apportare modifiche alla configurazione di Agent di registrazione. Le modifiche includono il parsing necessario per raggruppare le righe di registro che dovrebbero essere unite in un unico record di registro.

Informazioni su multilinea

Nei cluster OpenShift e Kubernetes, il sistema di logging cattura i log dai flussi delle applicazioni stdout e stderr. Aggiunge quindi un prefisso a ogni riga di registro con i metadati prima di memorizzare i registri in file, seguendo il formato di registrazione Container Runtime Interface (CRI).

Questo prefisso della riga di registro Kubernetes contiene:

Timestamp: In formato ISO 8601.
Nome del flusso: stdout o stderr.
Tag: F o P.

Il formato di registrazione CRI utilizza dei tag per definire se una riga di registro è una riga di registro singola o una voce di registro multilinea. I valori validi per il tag sono:

Partial (P): Questo tag è incluso nelle righe di log che sono il risultato della divisione di una singola riga di log in più righe da parte del runtime e la voce di log non è ancora terminata.
Full (F): Questo tag viene utilizzato per indicare che la voce di registro è stata completata. Viene utilizzato per una singola riga di registro o per indicare che si tratta dell'ultima riga di una voce a più righe.

2024-03-15T10:30:45.123456789Z stdout F This is a complete log line
2024-03-15T10:30:45.123456789Z stderr P This is the first part of a
2024-03-15T10:30:45.123456789Z stderr F multiline error message

Per impostazione predefinita, Agent di registrazione include la configurazione di Tail plugin con il parser multilinea di cri per supportare la concatenazione di questi log in formato CRI da stdout e stderr in un'unica riga di log.

Negli ambienti Kubernetes che utilizzano il logging basato su CRI, si raccomanda di utilizzare l'impostazione Multiline.Parser (impostata di default su cri ) per analizzare e riassemblare correttamente i log multilinea generati dai contenitori.

Potreste anche avere applicazioni, come Java o Python, in cui gli errori e le tracce di stack possono estendersi su più righe e ogni riga viene inviata come voce di registro separata. Queste applicazioni possono generare più linee di log che possono essere associate tra loro in un'unica linea di log. Per gestire questi registri multilinea attraverso Agent di registrazione, è necessario configurare un ulteriore Multiline parser.

Configurazione multilinea predefinita

La configurazione multilinea predefinita per i registri CRI viene configurata e abilitata quando si distribuisce il sito Agent di registrazione.

In Fluent Bit, è possibile configurare Multiline parser utilizzando il parser multilinea integrato o un parser multilinea personalizzato.

Per impostazione predefinita, Tail plugin, configurato con Agent di registrazione, è configurato con il parser multiline incorporato di cri. Questo parser elabora i log generati dal motore del contenitore CRI-O e supporta la concatenazione delle voci di log.

Ad esempio, il sito Agent di registrazione ha questa configurazione predefinita per il supporto multilinea:

    [INPUT]
        Name              tail
        Tag               kube.*
        .....
        Buffer_Chunk_Size 32KB
        Buffer_Max_Size   256KB
        Multiline.parser  cri
        Skip_Long_Lines   On
        Refresh_Interval  10
        storage.type      filesystem
        storage.pause_on_chunks_overlimit on

Configurazione di un supporto multilinea aggiuntivo per le applicazioni

Se si dispone di applicazioni, come Java o Python, in cui gli errori e le tracce di stack possono estendersi su più righe e ogni riga viene inviata come voce di registro separata, è necessario configurare il parser multilinea in Agent di registrazione.

Scegliere una delle seguenti opzioni per configurare il sito Agent di registrazione con il parser multilinea:

Distribuire l'agente Agent di registrazione aggiungendo un nuovo valore enableMultiline nel file logs-values.yaml che si usa per distribuire l'agente usando un grafico Helm. Per ulteriori informazioni, vedere Configurazione del file dei valori del grafico Helm per Agent di registrazione o Configurazione del file dei valori del grafico Helm per Agent di registrazione.
Aggiornare il sito Agent di registrazione alla versione 1.4.1 o superiore. È necessario aggiornare il file Helm chart logs-values.yaml con la versione dell'agente e impostare enableMultiline su true per abilitare il supporto multilinea. Per ulteriori informazioni, vedere Aggiornamento del file dei valori del grafico Helm per l'agente di registrazione.

Aggiunta di un parser multilinea personalizzato

Per creare un parser multilinea personalizzato da utilizzare con Agent di registrazione, seguire le istruzioni riportate in Parser multilinea configurabili. Si definirà una regex personalizzata per determinare lo schema multilinea.

La configurazione di Agent di registrazione deve includere anche un FILTER dopo il plugin INPUT. Il filtro applicherà il modello del sito configurato MULTILINE_PARSER. Il valore Name di MULTILINE_PARSER deve corrispondere al valore Multiline.parser di FILTER.

filter-multiline.conf: |
    [FILTER]
        Name              multiline
        Match             *
        Multiline.parser  INSERT_CUSTOM_PARSER_NAME
        Multiline.key_content log

Aggiunta del supporto multilinea per le app

Se si dispone di Agent di registrazione e di applicazioni come Java o Python, dove gli errori e le tracce di stack possono estendersi su più righe e ogni riga viene inviata come voce di registro separata, è possibile aggiornare la configurazione dell'agente e configurare il parser multilinea.

Completare i seguenti passaggi per aggiungere il supporto multilinea nel sito Agent di registrazione:

Accedi al cluster. Per ulteriori informazioni, vedere Accesso al cluster.

Nella mappa di configurazione di Agent di registrazione (inputs.conf), aggiungere il parser multilinea.

La configurazione di Agent di registrazione deve avere @INCLUDE per il filtro multilinea subito dopo il plug-in di ingresso.

fluent-bit.conf: |
[SERVICE]
  Flush                   1
  Log_Level               info
  Daemon                  off
  Parsers_File            parsers.conf
  Plugins_File            plugins.conf

  ...


@INCLUDE input-kubernetes.conf
@INCLUDE filter-multiline.conf

...

input-kubernetes.conf: |
[INPUT]
    Name              tail
    Tag               kube.*
    .....
    Buffer_Chunk_Size 32KB
    Buffer_Max_Size   256KB
    Multiline.parser  cri
    Skip_Long_Lines   On
    Refresh_Interval  10
    storage.type      filesystem
    storage.pause_on_chunks_overlimit on

filter-multiline.conf: |
[FILTER]
    Name              multiline
    Match             *
    Multiline.parser  multiline-java-example
    Multiline.key_content log

parsers.conf: |
...
[MULTILINE_PARSER]
    Name            multiline-java-example
    Type            regex
    Flush_timeout   500
    Rule            "start_state"     "/^(\d+-\d+-\d+ \d+:\d+:\d+\.\d+)(.*)$/"     "cont"
    Rule            "cont"            "/^(?!\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d{3}).*$/"     "cont"
...

Riavviare i pod dell'agente.

Per i cluster Kubernetes, eseguire:

kubectl -n ibm-observe rollout restart ds/logs-agent

Per i cluster OpenShift, eseguire:

oc -n ibm-observe rollout restart ds/logs-agent

Configurazione del supporto multilinea per cluster con più runtime e requisiti di parsing

Se si dispone di cluster che eseguono applicazioni con più linguaggi o runtime diversi (ad esempio, Java, Go e Python ), potrebbe essere necessario gestire log multilinea da varie fonti. Se si dispone già di un parser multilinea personalizzato per Java, è possibile combinarlo con i parser integrati per altri runtime come Go e Python. Questo assicura che tutti i registri siano analizzati correttamente e inoltrati come voci raggruppate correttamente a IBM® Cloud Logs.

Specificando più parser (incorporati e personalizzati) in un elenco separato da virgole, Agent di registrazione proverà ogni parser in sequenza fino a trovare una corrispondenza.

Configurazione di più parser con Helm

Se si usa Helm per configurare l'ambiente orchestrato, aggiornare la sezione multilinePreprocessor per fare riferimento a entrambi i parser incorporati (per esempio, go, python) con i parser personalizzati in un elenco separato da virgole.

Ad esempio:

multilinePreprocessor:
  - name: multiline
    multiline.parser: go, python, nodejs, ruby, multiline-java-example, multiline-nodejs-winston
    multiline.key_content: log

Se è stata installata una versione precedente di Agent di registrazione e si è aggiornata la configurazione dell'agente modificando la mappa di configurazione direttamente nel cluster, eseguire una copia della mappa di configurazione dal cluster prima di eseguire il comando helm upgrade. Quando il sito Agent di registrazione viene aggiornato, le modifiche apportate alla mappa di configurazione vengono sovrascritte.

Dopo aver aggiornato il file values.yaml, eseguire helm upgrade per applicare le modifiche. Verificare la configurazione controllando i log di diversi runtime in IBM Cloud Logs per assicurarsi che il raggruppamento multilinea funzioni in tutte le configurazioni.

Ulteriori informazioni ed esempi

Per ulteriori informazioni ed esercitazioni con scenari di esempio per la configurazione dell'elaborazione multilinea, vedere i seguenti argomenti.

Risorse aggiuntive per l'elaborazione multilinea Agent di registrazione
Per informazioni su	Consulta
Configurazione del supporto multilinea per il sito Agent di registrazione in Linux	Argomento
Configurazione del supporto multilinea per il sito Agent di registrazione in Windows	Argomento
Parsing multilinea per le applicazioni di Java con Log4j	Supporto didattico
Parsing multilineare con Helm per applicazioni Java con Log4j	Supporto didattico
Parsing multilineare per applicazioni Node.js con Winston	Supporto didattico
Parsing multilinea con Helm per applicazioni Node.js con Winston	Supporto didattico