Configura la rotazione dei log di AlloyDB Omni

Seleziona una versione della documentazione:

Questo documento descrive come configurare la rotazione dei log di diagnostica di AlloyDB Omni quando utilizzi l'operatore Kubernetes di AlloyDB Omni.

I seguenti file di log si trovano nella directory /obs/diagnostic/:

  • postgresql.log: questo file di log raccoglie i log del server PostgreSQL, ad esempio connessioni client, query e avvisi amministrativi. Questi log vengono sempre raccolti e non devono essere abilitati.

  • postgresql.audit: questo file di log raccoglie gli audit log di accesso alle sessioni e agli oggetti. Per raccogliere gli audit log, consulta Gestisci gli audit log con pgAudit.

  • postgresql.internal: AlloyDB Omni fornisce più messaggi oltre ai normali log di PostgreSQL. Questi messaggi forniscono ulteriori informazioni tecniche che possono essere utili per il debug dei problemi del database.

Comprendere e configurare la rotazione dei log

Scopri come AlloyDB Omni gestisce la rotazione dei log e come configurare le soglie di rotazione in base alle dimensioni o alla durata del file.

Comportamento della rotazione log

Quando un file di log viene ruotato, si verifica quanto segue:

  1. Il file di log esistente viene archiviato nella directory /obs/diagnostic/archive/.

  2. Il file di log attivo in /obs/diagnostic/ viene reimpostato in modo che le voci di log successive inizino a essere scritte in un file vuoto.

  3. Le informazioni di log continuano a essere scritte nel file di log attivo finché il file non raggiunge una soglia di dimensione o età, dopodiché viene ruotato di nuovo. I log vengono ruotati in modo che i file di log attivi non diventino troppo grandi.

Per impostazione predefinita, l'impostazione di rotazione prevede che ogni file di log ruoti quando le sue dimensioni raggiungono i 200 MB. La rotazione predefinita non include un'impostazione dell'età.

I file archiviati vengono conservati per 7 giorni. I file archiviati più vecchi di 7 giorni vengono rimossi automaticamente, ad eccezione del file archiviato durante l'ultima rotazione. Ad esempio, se log_rotation_age ha più di 7 giorni, il file archiviato raggiunge la soglia di 7 giorni prima della rotazione del file corrente. In questo caso, il file archiviato non viene rimosso fino alla rotazione successiva, che genera un nuovo file archiviato.

Ogni nome file di log ruotato segue il formato postgresql-%Y-%m-%d_%H%M%S.EXTENSION.gz, dove EXTENSION è log, audit o internal. Il periodo di rotazione determina il timestamp nel fuso orario UTC (Coordinated Universal Time). Ad esempio, se un file di log viene ruotato alle 13:01:02 del 20 dicembre 2024 UTC, il nome del file archiviato è postgresql-2024-12-20_130102.log.gz.

Il sistema comprime ogni file archiviato singolarmente utilizzando il formato gzip.

Configura le soglie di rotazione

Per controllare quando i log vengono ruotati, configura una dimensione massima del file, una durata tra le rotazioni dei log o entrambe. La durata tra le rotazioni dei log è chiamata anche età del log. Se utilizzi entrambe le impostazioni, ogni log viene ruotato quando raggiunge una delle soglie.

Per configurare la rotazione log, imposta uno o entrambi i seguenti parametri nella sezione parameters del manifest DBCluster:

  • log_rotation_size: "SIZE_IN_KB"
  • log_rotation_age: "AGE_IN_MINUTES"

Sostituisci quanto segue:

  • SIZE_IN_KB: la dimensione massima del file, in kilobyte, prima della rotazione dei log.
  • AGE_IN_MINUTES: la durata tra le rotazioni log, in minuti.

Per disattivare una delle impostazioni di rotazione log, impostala su zero, "0". Per mantenere l'impostazione predefinita che ruota i log quando le dimensioni del file raggiungono i 200 MB, non impostare nessuno dei due parametri.

Rotazione in base alle dimensioni e alla durata dei log

I seguenti set di esempio impostano la rotazione dei log quando le dimensioni del file raggiungono 400 MB o quando il tempo tra le rotazioni dei log raggiunge un giorno, a seconda di quale evento si verifica per primo:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
spec:
...
  primarySpec:
  ...
    parameters:
      log_rotation_size: "400000" # 400 MB
      log_rotation_age: "1440" # 24 hours * 60 minutes = 1 day

Sostituisci DB_CLUSTER_NAME con il nome del cluster di database.

Ruota solo in base alle dimensioni del log

L'esempio seguente imposta la rotazione dei log quando le dimensioni del file raggiungono i 400 MB:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
spec:
...
  primarySpec:
  ...
    parameters:
      log_rotation_size: "400000" # 400 MB
      log_rotation_age: "0" # Set to 0 to disable

Sostituisci DB_CLUSTER_NAME con il nome del cluster di database.

Ruota solo in base alla durata

Il seguente esempio imposta la rotazione dei log una volta ogni 24 ore:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
spec:
...
  primarySpec:
  ...
    parameters:
      log_rotation_size: "0" # Set to 0 to disable
      log_rotation_age: "1440" # 24 hours * 60 minutes = 1 day

Sostituisci DB_CLUSTER_NAME con il nome del cluster di database.

Parametri di logging PostgreSQL supportati

Puoi configurare le informazioni emesse in postgresql.log impostando i parametri GUC (Grand Unified Configuration) di logging PostgreSQL standard nella sezione parameters del manifest DBCluster:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
spec:
...
  primarySpec:
  ...
    parameters:
      log_min_messages: "warning"
      log_min_duration_statement: "250" # Log queries taking >= 250ms
      log_statement: "ddl" # Log all DDL statements
      log_lock_waits: "on"
      log_checkpoints: "on"
      log_temp_files: "0" # Log all temporary files created
      log_autovacuum_min_duration: "1000" # Log autovacuum runs taking >= 1s

Sostituisci DB_CLUSTER_NAME con il nome del cluster di database.

La tabella seguente descrive i parametri di logging di PostgreSQL supportati in base a Segnalazione di errori e logging nella documentazione di PostgreSQL.

Parametro Descrizione
log_min_messages Controlla quali livelli di messaggi vengono scritti nel log del server. I valori validi sono debug5, debug4, debug3, debug2, debug1, info, notice, warning, error, log, fatal e panic. Ogni livello include tutti i livelli di gravità successivi.
log_min_error_statement Controlla quali istruzioni SQL che causano una condizione di errore vengono registrate nel log del server. I valori validi sono compresi tra debug5 e panic. Per disattivare la registrazione degli errori delle istruzioni, imposta panic.
log_min_duration_statement Registra la durata di ogni istruzione completata se l'istruzione è stata eseguita per almeno il numero di millisecondi specificato. Se imposti questo parametro su 0, vengono registrate tutte le istruzioni e le durate. Se imposti questo parametro su -1, il logging della durata viene disattivato.
log_min_duration_sample I campioni completati vengono eseguiti per almeno i millisecondi specificati, alla velocità impostata da log_statement_sample_rate. Se imposti questo parametro su -1, il logging della durata campionata viene disattivato.
log_statement_sample_rate Specifica la frazione di istruzioni che superano log_min_duration_sample che vengono registrate (da 0.0 a 1.0).
log_transaction_sample_rate Specifica la frazione di transazioni le cui istruzioni vengono tutte registrate (da 0.0 a 1.0), indipendentemente dalla durata dell'esecuzione delle istruzioni.
log_statement Controlla quali istruzioni SQL vengono registrate: none (off), ddl (tutti i comandi di definizione dei dati), mod (DDL più istruzioni di modifica dei dati come INSERT, UPDATE e DELETE) o all.
log_duration Registra la durata di ogni istruzione completata. Il testo della query non viene stampato a meno che non venga superata anche la soglia log_min_duration_statement.
log_line_prefix Specifica l'output del prefisso in stile printf all'inizio di ogni riga di log (ad esempio %m per il timestamp, %p per l'ID processo, %u per l'utente e %d per il database).
log_connections Controlla se le connessioni client al database vengono registrate.
log_disconnections Controlla se le terminazioni e le durate delle sessioni vengono registrate.
log_hostname Controlla se il nome host del client di connessione viene registrato oltre al suo indirizzo IP.
log_error_verbosity Controlla il livello di dettaglio nei messaggi di log del server: terse, default o verbose (include il codice SQLSTATE e le righe di origine).
log_lock_waits Controlla se un messaggio viene registrato quando una sessione attende più di deadlock_timeout per acquisire un blocco.
log_lock_failures Controlla se viene registrato un messaggio quando l'acquisizione di un blocco non riesce (ad esempio, quando utilizzi SELECT ... NOWAIT).
log_checkpoints Registra i checkpoint e i restartpoint nel log, incluse le statistiche e i tempi di scrittura del buffer.
log_autovacuum_min_duration Registra ogni azione eseguita da autovacuum se è stata eseguita per almeno il numero specificato di millisecondi. Se imposti questo parametro su 0, vengono registrate tutte le azioni. Se imposti questo parametro su -1, il logging viene disattivato.
log_temp_files Controlla il logging dei nomi e delle dimensioni dei file temporanei in kilobyte quando vengono eliminati (per ordinamenti, hash o risultati delle query). Se imposti questo parametro su 0, vengono registrati tutti i file temporanei. Se imposti questo parametro su -1, il logging viene disattivato.
log_parameter_max_length Tronca i valori dei parametri di associazione registrati nei log delle istruzioni non di errore a questo numero di byte. Se imposti questo parametro su -1, i valori vengono registrati per intero. Se imposti questo parametro su 0, il logging dei parametri viene disattivato.
log_parameter_max_length_on_error Tronca i valori dei parametri di associazione riportati nei messaggi di errore a questo numero di byte. Se imposti questo parametro su 0, i parametri nei messaggi di errore vengono disattivati. Se lo imposti su -1, i valori vengono registrati per intero.
log_replication_commands Controlla se i comandi di replica e le azioni dello slot di replica vengono registrati.
log_recovery_conflict_waits Controlla se un messaggio viene registrato quando la procedura di avvio attende più di deadlock_timeout per i conflitti di recupero.
log_startup_progress_interval Imposta il tempo in millisecondi tra i messaggi di avanzamento per le operazioni di avvio a lunga esecuzione. Se imposti questo parametro su 0, lo disattivi.
log_timezone Imposta il fuso orario utilizzato per i timestamp nel log del server.

Gestire gli audit log con pgAudit

Per abilitare il logging degli accessi a sessioni e oggetti, devi configurare i parametri pgAudit nel cluster di database e installare l'estensione nei database.

Passaggio 1: configura i parametri pgAudit nel manifest DBCluster

Per raccogliere i log di accesso a sessioni e oggetti nel file postgresql.audit, attiva pgAudit e configura le istruzioni da registrare utilizzando il parametro pgaudit.log.

Aggiungi le seguenti righe alla sezione parameters del file v1_dbcluster_parameters.yaml:

alloydb.enable_pgaudit: "on"
pgaudit.log: "all"

L'esempio seguente mostra questa configurazione nel manifest DBCluster:

apiVersion: alloydbomni.dbadmin.goog/v1
kind: DBCluster
metadata:
  name: DB_CLUSTER_NAME
spec:
  databaseVersion: "18.3.0"
  primarySpec:
    ...
    parameters:
      ...
      alloydb.enable_pgaudit: "on"
      pgaudit.log: "all"

Sostituisci DB_CLUSTER_NAME con il nome del cluster di database.

Per ulteriori informazioni, consulta pgaudit in Estensioni di database supportate.

Passaggio 2: installa l'estensione pgAudit in ogni database

Dopo aver configurato i parametri e riavviato il database, connettiti al database e installa l'estensione pgAudit:

CREATE EXTENSION IF NOT EXISTS pgaudit;

Esegui questo comando in ogni database in cui vuoi attivare l'audit logging. Questo comando installa i trigger di eventi necessari per l'audit DDL.

Parametri pgAudit supportati

La tabella seguente descrive i parametri pgAudit chiave che puoi configurare nella sezione parameters della specifica DBCluster. Per ulteriori informazioni, consulta la documentazione di pgAudit.

Parametro Descrizione Valore predefinito
pgaudit.log Specifica quali classi di istruzioni vengono registrate dall'audit logging della sessione. I valori validi sono none, all, read, write, function, role, ddl, misc e misc_set. none
pgaudit.log_catalog Specifica che la registrazione della sessione è attivata se tutte le relazioni in un'istruzione si trovano in pg_catalog. La disattivazione di questa opzione riduce il rumore dei log dei client di database. on
pgaudit.log_parameter Specifica che l'audit logging include i parametri trasmessi con l'istruzione. off
pgaudit.log_relation Specifica se l'audit della sessione crea una voce di log separata per ogni relazione (come tabelle e viste) a cui viene fatto riferimento in un'istruzione SELECT o DML. off
pgaudit.log_rows Specifica che la registrazione degli audit include il numero di righe recuperate o interessate da un'istruzione. off
pgaudit.log_statement Specifica se il logging include il testo e i parametri dell'istruzione. on
pgaudit.role Specifica il ruolo principale da utilizzare per l'audit logging degli oggetti. Nessuno

I log del server PostgreSQL vengono sempre raccolti nel file postgresql.log e non richiedono l'attivazione di pgAudit.

Recupera il percorso dell'audit log attivo

Utilizza la funzione SQL alloydb_audit_current_logfile per visualizzare il percorso del file di log di controllo. Se il controllo è disattivato, il risultato è NULL.

SELECT alloydb_audit_current_logfile();

 alloydb_audit_current_logfile
----------------------------------
 /obs/diagnostic/postgresql.audit

Inoltra i log del database a un sink centralizzato

AlloyDB Omni scrive i log del server di database (postgresql.log), i log di controllo (postgresql.audit) e i log interni (postgresql.internal) nella directory /obs/diagnostic/ sul volume obsdisk all'interno del container del database.

Per inoltrare questi log a un sink di logging centralizzato (ad esempio Cloud Logging, Datadog, Splunk o Elasticsearch), puoi eseguire il deployment di un container sidecar utilizzando la risorsa personalizzata (CR) Sidecar.

Il container sidecar viene eseguito nello stesso pod del database, monta il volume dei log (obsdisk) e segue i file di log per inoltrarli alla destinazione di logging.

Esempio: inoltra i log utilizzando un sidecar Fluent Bit

L'esempio seguente mostra come utilizzare un sidecar Fluent Bit per seguire tutti i file di log di AlloyDB Omni e scriverli nell'output standard. I raccoglitori di log dei cluster Kubernetes standard, come l'agente Logging su Google Kubernetes Engine (GKE), possono quindi raccogliere questi log.

  1. Crea un ConfigMap contenente la configurazione di Fluent Bit per i file di log del server, di controllo e interni:

    apiVersion: v1
kind: ConfigMap
metadata:
  name: fluentbit-config
  namespace: NAMESPACE
data:
  fluent-bit.conf: |
    [SERVICE]
        Flush        1
        Daemon       Off
        Log_Level    info

    [INPUT]
        Name         tail
        Path         /obs/diagnostic/postgresql.log,/obs/diagnostic/postgresql.audit,/obs/diagnostic/postgresql.internal
        Tag          alloydb.*
        Path_Key     filename
        DB           /tmp/fluent-bit.db

    [OUTPUT]
        Name         stdout
        Match        *

    Sostituisci NAMESPACE con lo spazio dei nomi del cluster di database.

  2. Crea un manifest Sidecar che definisce il container Fluent Bit e monta sia il volume obsdisk (contenente i log di AlloyDB Omni) sia il volume ConfigMap:

    apiVersion: alloydbomni.dbadmin.goog/v1
kind: Sidecar
metadata:
  name: logging-forwarder
  namespace: NAMESPACE
spec:
  additionalVolumes:
  - name: fluentbit-config-volume
    configMap:
      name: fluentbit-config
  sidecars:
  - name: fluent-bit
    image: fluent/fluent-bit:3.0
    command: ["/fluent-bit/bin/fluent-bit"]
    args: ["-c", "/fluent-bit/etc/fluent-bit.conf"]
    volumeMounts:
    - name: obsdisk
      mountPath: /obs
    - name: fluentbit-config-volume
      mountPath: /fluent-bit/etc/

    Sostituisci NAMESPACE con lo spazio dei nomi del cluster di database.

  3. Aggiorna il manifest DBCluster per fare riferimento al sidecar o applica una patch al cluster utilizzando il seguente comando:

    kubectl patch dbclusters.alloydbomni.dbadmin.goog DB_CLUSTER_NAME -n NAMESPACE -p '{"spec":{"primarySpec":{"sidecarRef":{"name":"logging-forwarder"}}}}' --type=merge

    Sostituisci quanto segue:

    • DB_CLUSTER_NAME: il nome del cluster di database.
    • NAMESPACE: lo spazio dei nomi del cluster di database.

    Per saperne di più sulla gestione dei sidecar, consulta Configurare un container sidecar.

Cronologia della rotazione dei log delle query con SQL

Quando i file di log vengono ruotati, l'operatore archivia i file archiviati nella directory /obs/diagnostic/archive/ con i timestamp di rotazione formattati come postgresql-%Y-%m-%d_%H%M%S.EXTENSION.gz.

Puoi eseguire query sull'ora dell'ultima rotazione log direttamente dal database utilizzando le funzioni del file system PostgreSQL standard.

Controlla i timestamp di rotazione dai nomi file dei log archiviati

Per visualizzare le rotazioni dei log più recenti e i relativi timestamp di rotazione UTC analizzati, esegui la seguente query:

SELECT
  file,
  to_timestamp(
    substring(file from 'postgresql-([0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]{6})') || '+00',
    'YYYY-MM-DD_HH24MISS+TZH'
  ) AS rotated_at
FROM pg_ls_dir('/obs/diagnostic/archive') AS file
WHERE file ~ '^postgresql-[0-9]{4}-[0-9]{2}-[0-9]{2}_[0-9]{6}'
ORDER BY rotated_at DESC
LIMIT 5;

L'output è simile al seguente:

                   file                   |       rotated_at
------------------------------------------+------------------------
 postgresql-2026-09-29_171900.internal.gz | 2026-09-29 17:19:00+00
 postgresql-2026-09-29_072800.log.gz      | 2026-09-29 07:28:00+00
 postgresql-2026-09-28_175300.log.gz      | 2026-09-28 17:53:00+00
 postgresql-2026-09-28_093400.log.gz      | 2026-09-28 09:34:00+00
 postgresql-2026-09-28_092000.audit.gz    | 2026-09-28 09:20:00+00
(5 rows)

Passaggi successivi