logger-socket: Библиотека логирования на основе сырого сокета для NGINX (на основе nginx-module-lua)

Установка

Если вы еще не подписались на RPM-репозиторий, зарегистрируйтесь. После этого вы можете продолжить с следующими шагами.

CentOS/RHEL 7 или 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

Чтобы использовать эту библиотеку Lua с NGINX, убедитесь, что nginx-module-lua установлен.

Этот документ описывает lua-resty-logger-socket v0.1, выпущенный 18 февраля 2015 года.

Эта библиотека Lua является модулем удаленного логирования для ngx_lua:

http://wiki.nginx.org/HttpLuaModule

Она предназначена для замены стандартного модуля Nginx ngx_http_log_module для отправки логов доступа на удаленный сервер через неблокирующий сокет. Общий удаленный сервер логов, поддерживающий сокеты, — это syslog-ng.

Эта библиотека Lua использует API cosocket от ngx_lua, который обеспечивает 100% неблокирующее поведение.

Синопсис

    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, "не удалось инициализировать логгер: ",
                                err)
                        return
                    end
                end

                -- создайте пользовательское сообщение лога доступа в
                -- переменной Lua "msg"

                local bytes, err = logger.log(msg)
                if err then
                    ngx.log(ngx.ERR, "не удалось записать сообщение: ", err)
                    return
                end
            ';
        }
    }

Методы

Этот модуль логирования предназначен для совместного использования внутри рабочего процесса Nginx всеми запросами. Поэтому в настоящее время поддерживается только один удаленный сервер логов. В будущем мы можем поддерживать шардирование нескольких серверов логов.

init

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

Инициализирует логгер с пользовательскими конфигурациями. Этот логгер должен быть инициализирован перед использованием. Если вы не инициализируете логгер, вы получите ошибку.

Доступные пользовательские конфигурации перечислены ниже:

flush_limit

Если размер буферизованных сообщений плюс размер текущего сообщения достигает (>=) этого предела (в байтах), буферизованные сообщения лога будут записаны на сервер логов. По умолчанию 4096 (4KB).
drop_limit

Если размер буферизованных сообщений плюс размер текущего сообщения превышает этот предел (в байтах), текущее сообщение лога будет отброшено из-за ограниченного размера буфера. По умолчанию drop_limit составляет 1048576 (1MB).
timeout

Устанавливает защиту по времени (в мс) для последующих операций, включая метод connect. Значение по умолчанию — 1000 (1 секунда).
host

Хост сервера логов.
port

Номер порта сервера логов.
path

Если сервер логов использует сокет типа unix domain, path — это путь к файлу сокета. Обратите внимание, что host/port и path не могут быть одновременно пустыми. Должен быть указан хотя бы один.
max_retry_times

Максимальное количество попыток повторного подключения после неудачного подключения к серверу логов или неудачной отправки сообщений лога на сервер логов.
retry_interval

Задержка времени (в мс) перед повторной попыткой подключения к серверу логов или повторной попыткой отправки сообщений лога на сервер логов, по умолчанию 100 (0.1с).
pool_size

Размер пула keepalive, используемого sock:keepalive. По умолчанию 10.
max_buffer_reuse

Максимальное количество повторного использования внутреннего буфера логирования перед созданием нового (для предотвращения утечки памяти).
periodic_flush

Периодический интервал сброса (в секундах). Установите в nil, чтобы отключить эту функцию.
ssl

Логическое значение, включить или отключить подключение через SSL. По умолчанию false.
ssl_verify

Логическое значение, включить или отключить проверку соответствия хоста и сертификата. По умолчанию true.
sni_host

Установите имя хоста для отправки в SNI и для использования при проверке соответствия сертификата.

initted

syntax: initted = logger.initted()

Получает логическое значение, указывающее, был ли этот модуль инициализирован (путем вызова метода init).

log

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

Записывает сообщение. По умолчанию сообщение лога будет буферизоваться в модуле логгера до тех пор, пока не будет достигнут flush_limit, в этом случае логгер сбросит все буферизованные сообщения на удаленный сервер логов через сокет. bytes — это количество байтов, успешно буферизованных в логгере. Если bytes равно nil, err — это строка, описывающая, какая ошибка произошла в этот раз. Если bytes не равен nil, то err — это предыдущее сообщение об ошибке. err может быть nil, когда bytes не равен nil.

flush

syntax: bytes, err = logger.flush()

Сбрасывает любые буферизованные сообщения на удаленный сервер немедленно. Обычно вам не нужно вызывать это вручную, так как сброс происходит автоматически, когда буфер заполняется.

GitHub

Вы можете найти дополнительные советы по конфигурации и документацию для этого модуля в репозитории GitHub для nginx-module-logger-socket.