Плагин syslog

Плагин syslog предназначен для отправки логов запросов на внешний Syslog-сервер. Логи можно передавать в формате JSON.

Параметр Обязательный Значение по умолчанию Допустимые значения Описание

host

Да

IP-адрес или имя хоста сервера Syslog

port

Да

Порт сервера Syslog

name

Нет

"sys logger"

Идентификатор сервера

timeout

Нет

3000

[1, …​]

Тайм-аут передачи данных на
upstream-сервер, мс

tls

Нет

false

Включает проверку TLS-соединения

flush_limit

Нет

4096

[1, …​]

Максимальный размер буфера (КБ).
При достижении указанного значения
буфер и текущее сообщение сбрасываются
и записываются на сервер

drop_limit

Нет

1048576

Максимальный размер буфера (КБ).
При превышении указанного значения
текущее сообщение отбрасывается

sock_type

Нет

"tcp"

["tcp", "udp"]

Используемый транспортный протокол

pool_size

Нет

5

[5, …​]

Размер пула keep-alive,
используемого sock:keepalive

log_format

Нет

Формат логов в виде JSON с парами
ключ-значение. Значения поддерживают
строки и вложенные объекты
(до 5 уровней вложенности,
более глубокие уровни обрезаются).
В строках допускается использование
переменных NGINX с префиксом $

include_req_body

Нет

false

[false, true]

При значении true
в лог добавляется тело запроса

include_req_body_expr

Нет

Условие для логирования тела запроса
при включённом include_req_body.
Тело запроса записывается только
если выражение возвращает true

max_req_body_bytes

Нет

524288

>=1

Максимальный размер тела запроса для
логирования. При превышении значение
обрезается

include_resp_body

Нет

false

[false, true]

При значении true
в лог добавляется тело ответа

include_resp_body_expr

Нет

Условие для логирования тела ответа
при включённом include_resp_body.
Ответ записывается только если
выражение возвращает true

max_resp_body_bytes

Нет

524288

>=1

Максимальный размер тела ответа для
логирования. При превышении значение
обрезается

Плагин поддерживает batch processor для агрегации и пакетной обработки записей. Это позволяет не отправлять данные слишком часто. Batch processor отправляет данные каждые 5 секунд или при достижении 1000 записей в очереди.

Пример meta_format:

"<46>1 2024-01-06T02:30:59.145Z 127.0.0.1 apisix 82324 - - {\"response\":{\"status\":200,\"size\":141,\"headers\":{\"content-type\":\"text/plain\",\"server\":\"APISIX/3.7.0\",\"transfer-encoding\":\"chunked\",\"connection\":\"close\"}},\"route_id\":\"1\",\"server\":{\"hostname\":\"baiyundeMacBook-Pro.local\",\"version\":\"3.7.0\"},\"request\":{\"uri\":\"/opentracing\",\"url\":\"http://127.0.0.1:1984/opentracing\",\"querystring\":{},\"method\":\"GET\",\"size\":155,\"headers\":{\"content-type\":\"application/x-www-form-urlencoded\",\"host\":\"127.0.0.1:1984\",\"user-agent\":\"lua-resty-http/0.16.1 (Lua) ngx_lua/10025\"}},\"upstream\":\"127.0.0.1:1982\",\"apisix_latency\":100.99999809265,\"service_id\":\"\",\"upstream_latency\":1,\"start_time\":1704508259044,\"client_ip\":\"127.0.0.1\",\"latency\":101.99999809265}\n"

Метаданные

Формат логов может быть задан на уровне метаданных плагина.

Параметр Описание

log_format

Формат логов в виде JSON-объекта с парами ключ–значение

Настройка метаданных плагина действует глобально. Это означает, что она применяется ко всем маршрутам и сервисам, где используется плагин syslog.

Ниже приведён пример настройки через Admin API:

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/syslog -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "log_format": {
        "host": "$host",
        "@timestamp": "$time_iso8601",
        "client_ip": "$remote_addr",
        "request": { "method": "$request_method", "uri": "$request_uri" },
        "response": { "status": "$status" }
    }
}'

admin_key можно получить из config.yaml и сохранить в переменную окружения следующей командой:

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

С этой конфигурацией логи будут иметь следующий формат:

{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"}
{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"}

Включение плагина

Включение плагина выполняется в веб-интерфейсе или в Admin API.

Включение в веб-интерфейсе

Перейти в раздел Маршруты → Плагины. Плагин, добавленный в этом разделе, применяется только к выбранному маршруту.

Либо перейти в раздел Конфигурация плагинов и выполнить настройку плагина. В этом случае создаётся конфигурация с ID, которую можно подключать к разным маршрутам и сервисам для переиспользования.

log syslog 1

В строке поиска ввести syslog и выбрать плагин. Нажать Add.

log syslog 2

Откроется форма конфигурации плагина. Необходимо задать параметры подключения к Syslog-серверу:

  • host — адрес Syslog-сервера

  • port — порт Syslog-сервера

  • flush_limit — размер буфера, при достижении которого происходит отправка логов

После заполнения параметров нажать Add в окне настройки плагина. После сохранения маршрута плагин начинает отправку логов запросов на указанный Syslog-сервер.

Включение в Admin API

Ниже приведён пример включения плагина для конкретного маршрута:

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "plugins": {
        "syslog": {
                "host" : "127.0.0.1",
                "port" : 5044,
                "flush_limit" : 1
            }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    },
    "uri": "/hello"
}'

Пример использования

После включения плагина каждый обработанный запрос отправляется на Syslog-сервер.

curl -i http://127.0.0.1:9080/hello

Удаление плагина

Чтобы удалить плагин syslog, нужно удалить соответствующую JSON-конфигурацию из конфигурации плагина.

curl http://127.0.0.1:9180/apisix/admin/routes/1  -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/hello",
    "plugins": {},
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'