Configurar a rotação de registro do AlloyDB Omni

Selecione uma versão da documentação:

Neste documento, descrevemos como configurar a rotação dos registros de diagnóstico do AlloyDB Omni ao usar o operador do AlloyDB Omni no Kubernetes.

Os seguintes arquivos de registro estão localizados no diretório /obs/diagnostic/:

  • postgresql.log: esse arquivo de registro coleta registros do servidor PostgreSQL, como conexões de clientes, consultas e avisos administrativos. Esses registros são sempre coletados e não precisam ser ativados.

  • postgresql.audit: esse arquivo de registro coleta registros de auditoria de acesso a sessões e objetos. Para coletar registros de auditoria, consulte Gerenciar registros de auditoria com pgAudit.

Entender e configurar a rotação de registros

Saiba como o AlloyDB Omni processa a rotação de registros e como configurar limiares de rotação com base no tamanho ou na duração do arquivo.

Comportamento de rotação de registros

Quando um arquivo de registro é rotacionado, acontece o seguinte:

  1. O arquivo de registro atual é arquivado no diretório /obs/diagnostic/archive/.

  2. O arquivo de registro ativo em /obs/diagnostic/ é redefinido para que as entradas de registro subsequentes comecem a ser gravadas em um arquivo limpo.

  3. As informações de registro continuam sendo gravadas no arquivo de registro ativo até que ele atinja um tamanho ou limite de idade, momento em que ele é rotacionado novamente. Os registros são rotacionados para que os arquivos de registro ativos não fiquem muito grandes.

Por padrão, a configuração de rotação é para cada arquivo de registro ser rotacionado quando o tamanho atinge 200 MB. A rotação padrão não inclui uma configuração de idade.

Os arquivos arquivados são retidos por sete dias. Os arquivos arquivados com mais de 7 dias são removidos automaticamente, exceto o arquivo arquivado durante a última rotação. Por exemplo, se log_rotation_age tiver mais de sete dias, o arquivo arquivado vai atingir o limite de sete dias antes da rotação do arquivo atual. Nesse caso, o arquivo arquivado não será removido até que a próxima rotação gere um novo arquivo arquivado.

Cada nome de arquivo de registro rotacionado segue o formato postgresql-%Y-%m-%d_%H%M%S.EXTENSION.gz, em que EXTENSION é log ou audit. O horário de rotação determina o carimbo de data/hora no Tempo Universal Coordenado (UTC). Por exemplo, se um arquivo de registro for rotacionado às 13h01min02s de 20 de dezembro de 2024 UTC, o nome de arquivo arquivado será postgresql-2024-12-20_130102.log.gz.

O sistema compacta cada arquivo arquivado individualmente usando o formato de arquivo gzip.

Configurar limites de rotação

Para controlar quando os registros são rotacionados, configure um tamanho máximo de arquivo, uma duração entre as rotações de registro ou ambos. A duração entre as rotações de registro também é chamada de idade do registro. Se você usar as duas configurações, cada registro será rotacionado quando atingir um dos limites.

Para configurar a rotação de registro, defina um ou ambos os parâmetros a seguir na seção parameters do manifesto DBCluster:

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

Substitua:

  • SIZE_IN_KB: o tamanho máximo do arquivo, em kilobytes, antes da rotação dos registros.
  • AGE_IN_MINUTES: a duração entre as rotações de registros, em minutos.

Para desativar uma das configurações de rotação de registro, defina-a como zero, "0". Para manter a configuração padrão que rotaciona os registros quando o tamanho do arquivo atinge 200 MB, não defina nenhum parâmetro.

Rotação por tamanho e duração do registro

O seguinte exemplo define a rotação dos registros quando o tamanho do arquivo atinge 400 MB ou quando o tempo entre as rotações atinge um dia, o que acontecer primeiro:

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

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados.

Fazer rotação apenas pelo tamanho do registro

O seguinte exemplo define a rotação dos registros quando o tamanho do arquivo atinge 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

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados.

Alternar apenas por duração

O seguinte exemplo define a rotação dos registros a cada 24 horas:

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

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados.

Parâmetros de registro do PostgreSQL compatíveis

É possível configurar quais informações são emitidas para postgresql.log definindo parâmetros padrão da Grand Unified Configuration (GUC) de geração de registros do PostgreSQL na seção parameters do manifesto 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

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados.

A tabela a seguir descreve os parâmetros de geração de registros do PostgreSQL compatíveis com base em Error Reporting e geração de registros na documentação do PostgreSQL.

Parâmetro Descrição
log_min_messages Controla quais níveis de mensagem são gravados no registro do servidor. Os valores válidos são debug5, debug4, debug3, debug2, debug1, info, notice, warning, error, log, fatal e panic. Cada nível inclui todos os níveis de gravidade a seguir.
log_min_error_statement Controla quais instruções SQL que causam uma condição de erro são registradas no log do servidor. Os valores válidos são de debug5 a panic. Para desativar a geração de registros de erros de instruções, defina como panic.
log_min_duration_statement Registra a duração de cada instrução concluída se ela foi executada por pelo menos o número especificado de milissegundos. Definir esse parâmetro como 0 registra todas as instruções e durações. Definir como -1 desativa o registro de duração.
log_min_duration_sample Amostra instruções concluídas em execução por pelo menos os milissegundos especificados, na taxa definida por log_statement_sample_rate. Definir como -1 desativa a geração de registros de duração amostrada.
log_statement_sample_rate Especifica a fração de instruções que excedem log_min_duration_sample e são registradas (0.0 a 1.0).
log_transaction_sample_rate Especifica a fração de transações cujas instruções são todas registradas (0.0 a 1.0), independentemente da duração da execução da instrução.
log_statement Controla quais instruções SQL são registradas: none (desativado), ddl (todos os comandos de definição de dados), mod (DDL mais instruções de modificação de dados, como INSERT, UPDATE e DELETE) ou all.
log_duration Registra a duração de cada instrução concluída. O texto da consulta não é impresso, a menos que o limite de log_min_duration_statement também seja excedido.
log_line_prefix Especifica a saída do prefixo no estilo printf no início de cada linha de registro (como %m para carimbo de data/hora, %p para ID do processo, %u para usuário e %d para banco de dados).
log_connections Controla se as conexões de cliente com o banco de dados são registradas.
log_disconnections Controla se os encerramentos e as durações de sessão são registrados.
log_hostname Controla se o nome do host do cliente de conexão é registrado além do endereço IP.
log_error_verbosity Controla o nível de detalhes nas mensagens de registro do servidor: terse, default ou verbose (inclui o código SQLSTATE e as linhas de origem).
log_lock_waits Controla se uma mensagem é registrada quando uma sessão espera mais do que deadlock_timeout para adquirir um bloqueio.
log_checkpoints Registra checkpoints e pontos de reinicialização no registro, incluindo estatísticas e tempo de gravação do buffer.
log_autovacuum_min_duration Registra cada ação executada pelo autovacuum se ela foi executada por pelo menos o número especificado de milissegundos. Definir esse parâmetro como 0 registra todas as ações. Definir como -1 desativa o registro.
log_temp_files Controla o registro de nomes e tamanhos de arquivos temporários em kilobytes quando excluídos (para ordenações, hashes ou resultados de consultas). Definir esse parâmetro como 0 registra todos os arquivos temporários. Definir como -1 desativa o registro em registros.
log_parameter_max_length Corta os valores de parâmetro de vinculação registrados em registros de instruções sem erros para esse número de bytes. Definir esse parâmetro como -1 registra valores por completo. Definir como 0 desativa o registro de parâmetros.
log_parameter_max_length_on_error Corta os valores de parâmetros de vinculação informados em mensagens de erro para esse número de bytes. Definir esse parâmetro como 0 desativa os parâmetros nas mensagens de erro. Definir como -1 registra os valores por completo.
log_replication_commands Controla se os comandos de replicação e as ações de slot de replicação são registrados.
log_recovery_conflict_waits Controla se uma mensagem é registrada quando o processo de inicialização espera mais de deadlock_timeout por conflitos de recuperação.
log_startup_progress_interval Define o tempo em milissegundos entre as mensagens de progresso para operações de inicialização de longa duração. Definir esse parâmetro como 0 o desativa.
log_timezone Define o fuso horário usado para carimbos de data/hora no registro do servidor.

Gerenciar registros de auditoria com pgAudit

Para ativar o registro de acesso a sessões e objetos, configure os parâmetros do pgAudit no cluster de banco de dados e instale a extensão nos bancos de dados.

Etapa 1: configurar parâmetros do pgAudit no manifesto do DBCluster

Para coletar registros de acesso a sessões e objetos no arquivo postgresql.audit, ative o pgAudit e configure quais instruções registrar usando o parâmetro pgaudit.log.

Adicione as seguintes linhas à seção parameters do arquivo v1_dbcluster_parameters.yaml:

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

O exemplo a seguir mostra essa configuração no manifesto DBCluster:

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

Substitua DB_CLUSTER_NAME pelo nome do cluster de banco de dados.

Para mais informações, consulte pgaudit em Extensões de banco de dados compatíveis.

Etapa 2: instale a extensão pgAudit em cada banco de dados

Depois de configurar os parâmetros e reiniciar o banco de dados, conecte-se a ele e instale a extensão pgAudit:

CREATE EXTENSION IF NOT EXISTS pgaudit;

Execute esse comando em todos os bancos de dados em que você quer ativar o registro de auditoria. Esse comando instala os gatilhos de eventos necessários para a auditoria de DDL.

Parâmetros do pgAudit aceitos

A tabela a seguir descreve os principais parâmetros do pgAudit que podem ser configurados na seção parameters da especificação DBCluster. Para mais informações, consulte a documentação do pgAudit.

Parâmetro Descrição Valor padrão
pgaudit.log Especifica quais classes de instruções são registradas pelo registro de auditoria de sessão. Os valores válidos são none, all, read, write, function, role, ddl, misc, e misc_set. none
pgaudit.log_catalog Especifica que o registro de sessão será ativado se todas as relações em uma instrução estiverem em pg_catalog. Desativar essa opção reduz o ruído de registro dos clientes do banco de dados. on
pgaudit.log_parameter Especifica que o registro de auditoria inclui os parâmetros transmitidos com a instrução. off
pgaudit.log_relation Especifica se a auditoria de sessão cria uma entrada de registro separada para cada relação (como tabelas e visualizações) referenciada em uma instrução SELECT ou DML. off
pgaudit.log_rows Especifica que o registro de auditoria inclui o número de linhas recuperadas ou afetadas por uma instrução. off
pgaudit.log_statement Especifica se o registro em log inclui o texto e os parâmetros da instrução. on
pgaudit.role Especifica a função principal a ser usada para o registro de auditoria de objetos. Nenhum

Os registros do servidor PostgreSQL são sempre coletados no arquivo postgresql.log e não exigem a ativação do pgAudit.

Encaminhar registros de banco de dados para um coletor centralizado

O AlloyDB Omni grava registros do servidor de banco de dados (postgresql.log) e registros de auditoria (postgresql.audit) no diretório /obs/diagnostic/ no volume obsdisk dentro do contêiner de banco de dados.

Para encaminhar esses registros a um coletor de registros centralizado (como Cloud Logging, Datadog, Splunk ou Elasticsearch), implante um contêiner sidecar usando o recurso personalizado (CR) Sidecar.

O contêiner secundário é executado no mesmo pod do banco de dados, monta o volume de registro (obsdisk) e acompanha os arquivos de registro para encaminhá-los ao destino de geração de registros.

Exemplo: encaminhar registros usando um sidecar do Fluent Bit

O exemplo a seguir demonstra como usar um sidecar do Fluent Bit para rastrear todos os arquivos de registro do AlloyDB Omni e gravá-los na saída padrão. Os coletores de registros de cluster padrão do Kubernetes, como o agente do Logging no Google Kubernetes Engine (GKE), podem coletar esses registros.

  1. Crie um ConfigMap com a configuração do Fluent Bit para rastrear arquivos de registro de auditoria e do servidor:

    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
        Tag          alloydb.*
        Path_Key     filename
        DB           /tmp/fluent-bit.db

    [OUTPUT]
        Name         stdout
        Match        *

    Substitua NAMESPACE pelo namespace do cluster de banco de dados.

  2. Crie um manifesto Sidecar que defina o contêiner do Fluent Bit e monte o volume obsdisk (que contém os registros do AlloyDB Omni) e o volume do 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/

    Substitua NAMESPACE pelo namespace do cluster de banco de dados.

  3. Atualize o manifesto DBCluster para referenciar o sidecar ou corrija o cluster usando o seguinte comando:

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

    Substitua:

    • DB_CLUSTER_NAME: o nome do cluster de banco de dados.
    • NAMESPACE: o namespace do cluster de banco de dados.

    Para mais informações sobre como gerenciar sidecars, consulte Configurar um contêiner sidecar.

Consultar o histórico de rotação de registros com SQL

Quando os arquivos de registro são rotacionados, o operador armazena os arquivos arquivados no diretório /obs/diagnostic/archive/ com os carimbos de data/hora de rotação formatados como postgresql-%Y-%m-%d_%H%M%S.EXTENSION.gz.

É possível consultar a hora da rotação de registros mais recente diretamente do banco de dados usando funções padrão do sistema de arquivos do PostgreSQL.

Inspecionar carimbos de data/hora de rotação nos nomes de arquivos de registro arquivados

Para conferir as rotações de registros mais recentes e os carimbos de data/hora de rotação UTC analisados, execute a seguinte consulta:

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;

O resultado será o seguinte:

                   file                   |       rotated_at
------------------------------------------+------------------------
 postgresql-2026-09-29_171900.log.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)

A seguir