Pular para conteúdo

logger-socket: Biblioteca de Logger baseada em socket bruto para NGINX (baseada em nginx-module-lua)

Instalação

Se você ainda não configurou a assinatura do repositório RPM, inscreva-se. Depois, você pode prosseguir com os seguintes passos.

CentOS/RHEL 7 ou Amazon Linux 2

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install lua-resty-logger-socket

CentOS/RHEL 8+, Fedora Linux, Amazon Linux 2023

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install lua5.1-resty-logger-socket

Para usar esta biblioteca Lua com o NGINX, certifique-se de que o nginx-module-lua esteja instalado.

Este documento descreve lua-resty-logger-socket v0.1 lançado em 18 de fevereiro de 2015.

Esta biblioteca Lua é um módulo de registro remoto para ngx_lua:

http://wiki.nginx.org/HttpLuaModule

Ela visa substituir o módulo padrão de log de acesso do Nginx ngx_http_log_module para enviar logs de acesso a um servidor remoto via um socket não bloqueante. Um servidor de log remoto comum que suporta sockets é o syslog-ng.

Esta biblioteca Lua aproveita a API de cosocket do ngx_lua, que garante um comportamento 100% não bloqueante.

Sinopse

    server {
        location / {
            log_by_lua '
                local logger = require "resty.logger.socket"
                if not logger.initted() then
                    local ok, err = logger.init{
                        host = 'xxx',
                        port = 1234,
                        flush_limit = 1234,
                        drop_limit = 5678,
                    }
                    if not ok then
                        ngx.log(ngx.ERR, "falha ao inicializar o logger: ",
                                err)
                        return
                    end
                end

                -- construa a mensagem de log de acesso personalizada na
                -- variável Lua "msg"

                local bytes, err = logger.log(msg)
                if err then
                    ngx.log(ngx.ERR, "falha ao registrar a mensagem: ", err)
                    return
                end
            ';
        }
    }

Métodos

Este módulo de logger foi projetado para ser compartilhado dentro de um processo worker do Nginx por todas as requisições. Portanto, atualmente, apenas um servidor de log remoto é suportado. Podemos suportar o particionamento de múltiplos servidores de log no futuro.

init

syntax: ok, err = logger.init(user_config)

Inicializa o logger com as configurações do usuário. Este logger deve ser inicializado antes de ser usado. Se você não inicializar o logger, receberá um erro.

As configurações de usuário disponíveis são listadas a seguir:

  • flush_limit

    Se o tamanho das mensagens em buffer mais o tamanho da mensagem atual atingir (>=) este limite (em bytes), as mensagens de log em buffer serão escritas no servidor de log. O padrão é 4096 (4KB).

  • drop_limit

    Se o tamanho das mensagens em buffer mais o tamanho da mensagem atual for maior que este limite (em bytes), a mensagem de log atual será descartada devido ao tamanho limitado do buffer. O limite padrão de drop_limit é 1048576 (1MB).

  • timeout

    Define o tempo limite (em ms) de proteção para operações subsequentes, incluindo o método connect. O valor padrão é 1000 (1 segundo).

  • host

    Host do servidor de log.

  • port

    Número da porta do servidor de log.

  • path

    Se o servidor de log usar um socket de domínio unix do tipo stream, path é o caminho do arquivo do socket. Observe que host/port e path não podem estar ambos vazios. Pelo menos um deve ser fornecido.

  • max_retry_times

    Número máximo de tentativas após uma conexão com um servidor de log falhar ou o envio de mensagens de log para um servidor de log falhar.

  • retry_interval

    O atraso (em ms) antes de tentar novamente conectar a um servidor de log ou tentar novamente enviar mensagens de log para um servidor de log, padrão é 100 (0,1s).

  • pool_size

    Tamanho do pool keepalive usado pelo sock:keepalive. O padrão é 10.

  • max_buffer_reuse

    Número máximo de reutilizações do buffer de log interno antes de criar um novo (para evitar vazamento de memória).

  • periodic_flush

    Intervalo de flush periódico (em segundos). Defina como nil para desativar este recurso.

  • ssl

    Booleano, habilita ou desabilita a conexão via SSL. O padrão é falso.

  • ssl_verify

    Booleano, habilita ou desabilita a verificação de correspondência entre host e certificado. O padrão é verdadeiro.

  • sni_host

    Define o nome do host a ser enviado em SNI e a ser usado ao verificar a correspondência do certificado.

initted

syntax: initted = logger.initted()

Obtém um valor booleano indicando se este módulo foi inicializado (chamando o método init).

log

syntax: bytes, err = logger.log(msg)

Registra uma mensagem. Por padrão, a mensagem de log será armazenada em buffer no módulo logger até que o flush_limit seja atingido, caso em que o logger enviará todas as mensagens em buffer para o servidor de log remoto via um socket. bytes é o número de bytes que foram armazenados com sucesso no logger. Se bytes for nil, err é uma string descrevendo que tipo de erro ocorreu desta vez. Se bytes não for nil, então err é uma mensagem de erro anterior. err pode ser nil quando bytes não é nil.

flush

syntax: bytes, err = logger.flush()

Descarrega imediatamente quaisquer mensagens em buffer para o remoto. Normalmente, você não precisa chamar isso manualmente, pois o descarregamento acontece automaticamente quando o buffer está cheio.

GitHub

Você pode encontrar dicas adicionais de configuração e documentação para este módulo no repositório GitHub para nginx-module-logger-socket.