Клиентское логирование

Передача логов с виртуальной машины с помощью Fluent Bit и Lua-скрипта

Fluent Bit — кроссплатформенный инструмент с открытым исходным кодом. Он собирает, обрабатывает и фильтрует лог-сообщения из разных источников, а затем сохраняет их в хранилище. После этого лог-сообщения поступают в маршрутизатор, который определяет, куда они будут отправлены. Для работы с разными источниками и приемниками используются специализированные плагины.

Перед началом работы

Создайте и настройте лог-группу.
Создайте сервисный аккаунт. В блоке Доступы и роли выберите роли:
- в блоке Проект — «Пользователь сервисов»;
- в блоке Сервисы — «logaas.writer».
Для сервисного аккаунта создайте API-ключ. В параметрах API-ключа укажите сервис «logging_as_a_service».

Срок действия API-ключа ограничен — когда он подойдет к концу, мы отправим вам уведомление. После этого необходимо обновить API-ключ.
Создайте виртуальную машину Ubuntu 22.04.
Подключитесь к созданной виртуальной машине по SSH.

Шаг 1. Установка Fluent Bit

Примечание

Возможно использование Fluent Bit версии 2.2 и выше. Рекомендуемая версия — 3.2.

Установите Fluent Bit одним из способов:

Установите приложение Fluent Bit из сборки дистрибутива для вашей операционной системы.

Чтобы проверить, что fluent-bit установлен корректно, нужно запустить его и убедиться, что он установлен как сервис. Для этого:

Запустите fluent-bit как сервис:
```
sudo systemctl start fluent-bit
```

Проверьте статус сервиса fluent-bit — он должен быть активным:

systemctl status fluent-bit

Если fluent-bit настроен верно, будет выведен статус в виде:

● fluent-bit.service - Fluent Bit
     Loaded: loaded (/lib/systemd/system/fluent-bit.service; disabled; vendor preset: enabled)
     Active: active (running) since Tue 2025-03-11 15:48:23 UTC; 3s ago
       Docs: https://docs.fluentbit.io/manual/
   Main PID: 34596 (fluent-bit)
      Tasks: 8 (limit: 2323)
     Memory: 9.4M
        CPU: 70ms
     CGroup: /system.slice/fluent-bit.service
             └─34596 /opt/fluent-bit/bin/fluent-bit -c //etc/fluent-bit/fluent-bit.conf

После проверки сервиса fluent-bit остановите его, чтобы далее настроить на совместную работу с logaas:
```
sudo systemctl stop fluent-bit
```

Шаг 2. Настройка Fluent Bit

Создайте файл logaas_format.lua для форматирования логов в формат сервиса «Клиентское логирование»:
```
sudo touch /etc/fluent-bit/logaas_format.lua
```
Откройте созданный файл с помощью редактора nano:
```
sudo nano /etc/fluent-bit/logaas_format.lua
```

В файл добавьте:

function format_log(tag, timestamp, record)
    -- 1. Project ID & Log Group ID
    local default_project_id = record.default_project_id
    local default_group_id = record.default_group_id

    local project_id = record.project_id
    if not project_id or project_id == "" then
        project_id = default_project_id
    end

    local group_id = record.group_id
    if not group_id or group_id == "" then
        group_id = default_group_id
    end

    record.default_project_id = nil
    record.default_group_id = nil

    -- 2. Timestamp
    local system_timezone = os.date("%z")
    local timezone_formatted = string.sub(system_timezone, 1, 3) .. ":" .. string.sub(system_timezone, 4, 5)
    local sec = timestamp.sec
    local nsec = timestamp.nsec
    local iso_timestamp = os.date("%Y-%m-%dT%H:%M:%S", sec)
    local milliseconds = string.format("%03d", math.floor(nsec / 1000000))
    local formatted_ts = iso_timestamp .. "." .. milliseconds .. timezone_formatted

    -- 3. Message
    local message = record.message
    if type(message) == "table" then
        message = cjson.encode(message)
    end

    -- 4. Label merging
    local default_labels = {}
    local keys_to_remove = {}
    local merged_labels = {}

    for key, value in pairs(record) do
        if key:find("^default_labels.") then
            local subkey = key:sub(16)
            default_labels[subkey] = value
            table.insert(keys_to_remove, key)
        end
    end

    for _, key in ipairs(keys_to_remove) do
        record[key] = nil
    end

    for k, v in pairs(default_labels) do
        merged_labels[k] = v
    end

    if record.labels then
        for k, v in pairs(record.labels) do
            merged_labels[k] = v
        end
    end

    -- 5. Build log
    local log_entry = {
        timestamp = formatted_ts,
        level = record.level or "INFO",
        project_id = project_id,
        log_group_id = group_id,
        labels = merged_labels,
        message = message
    }

    if record.trace_id and record.trace_id ~= "" then
        log_entry.trace_id = record.trace_id
    end

    if record.service_name and record.service_name ~= "" then
        log_entry.service_name = record.service_name
    end

    if record.instance_id and record.instance_id ~= "" then
        log_entry.instance_id = record.instance_id
    end

    -- 6. Complete
    return 1, timestamp, log_entry
end

Откройте файл /etc/fluent-bit/fluent-bit.conf:
```
sudo nano /etc/fluent-bit/fluent-bit.conf
```

Добавьте в него данные в виде:

[SERVICE]
    Daemon Off
    Flush 1
    Log_Level info
    Parsers_File parsers.conf
    storage.sync  full

[INPUT]
    Name tail
    Path <path-to-log/logfile.log>
    Parser docker

[FILTER]
    Name                parser
    Match               *
    Key_Name            log
    Parser              json
    Reserve_Data        true

# target section
[FILTER]
    name          modify
    match         *
    Set default_project_id REPLACE_TO_PROJECT_ID
    Set default_group_id REPLACE_TO_LOG_GROUP_ID

#default labels section
[FILTER]
    name          modify
    match         *
    Set default_labels.<label_name_1> value_A
    Set default_labels.<label_name_2> value_B

[FILTER]
    Name                lua
    Match               *
    Script              logaas_format.lua
    Call                format_log
    time_as_table       true

[OUTPUT]
    Name                http
    Match               *
    Host                logging.api.cloud.ru
    Port                443
    tls                 on
    URI                 /api/v1/logs-ingest
    json_date_key       false
    Header              Authorization Api-Key REPLACE_TO_SA_API_KEY

Секция [INPUT] указывает на источник логов, а [OUTPUT] — на сервис, в который отправятся логи.

В режиме tail сбор логов в fluent-bit работает по принципу отслеживания новых записей в логах. При перезапуске сервиса данные, обработанные ранее, не отправляются в систему повторно.

Измените файл, подставив в него свои данные:

<path-to-log/logfile.log> — путь к файлу-источнику логов: fluent-bit будет сканировать этот файл и отслеживать в нем новые строки.

REPLACE_TO_PROJECT_ID и REPLACE_TO_LOG_GROUP_ID — ID проекта и ID лог-группы, в которую будут отправлены логи. REPLACE_TO_LOG_GROUP_ID — необязательная строка. Если ее не добавить, логи отправятся в группу проекта по умолчанию (default-группа).

REPLACE_TO_SA_API_KEY — API-ключ сервисного аккаунта. Проверьте, что у вас есть доступ к проекту, а для вашего сервисного аккаунта выбраны роли «Пользователь сервисов» и «logaas.writer».

Секция default labels section — опциональная. В ней вы можете указать метки, которые будут добавлены ко всем логам. Это удобно для последующей фильтрации логов с помощью языка фильтрующих выражений. Метки указываются в виде default_labels.<label_name>, где <label_name> — имя метки, которая добавится к логам.

В следующем шаге инструкции настраивается тестовая отправка данных с помощью генератора логов, который записывает логи в лог-файл. Для тестирования с помощью генератора вместо <path-to-log/logfile.log> укажите путь к лог-файлу: /usr/local/bin/log_producer/error_log.log.

Пример изменений в файле /etc/fluent-bit/fluent-bit.conf:

[SERVICE]
    Daemon Off
    Flush 1
    Log_Level info
    Parsers_File parsers.conf
    storage.sync  full

[INPUT]
    Name tail
    Path /usr/local/bin/log_producer/error_log.log
    Parser docker

[FILTER]
    Name                parser
    Match               *
    Key_Name            log
    Parser              json
    Reserve_Data        true

# target section
[FILTER]
    name          modify
    match         *
    Set default_project_id 00000000-1111-2222-3333-444444444444
    Set default_group_id aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

#default labels section
[FILTER]
    name          modify
    match         *
    Set default_labels.some_field_A value_A
    Set default_labels.some_field_B value_B

[FILTER]
    Name                lua
    Match               *
    Script              logaas_format.lua
    Call                format_log
    time_as_table       true

[OUTPUT]
    Name                http
    Match               *
    Host                logging.api.cloud.ru
    Port                443
    tls                 on
    URI                 /api/v1/logs-ingest
    json_date_key       false
    Header              Authorization Api-Key ZDVkNmVlY2EtxxxxxxxxxxxxxxxxhYTJhNGJl.xxxxxxxxxxxxx

Шаг 3. Проверка отправки логов

На этом этапе вы сможете настроить тестовую отправку логов с помощью bash-скрипта — генератора логов. Он будет записывать логи в лог-файл.

Чтобы создать генератор:

Создайте директорию, в которой будет находиться скрипт:
```
sudo mkdir /usr/local/bin/log_producer/
```

Создайте пустой файл log_producer.sh:

sudo touch /usr/local/bin/log_producer/log_producer.sh

Откройте созданный файл с помощью редактора nano:

sudo nano /usr/local/bin/log_producer/log_producer.sh

В файл добавьте:

#!/bin/bash

LOG_FILE=${1:-./error_log.log}

generate_log() {
    # Generate timestamp with timezone
    timestamp=$(date "+%Y-%m-%dT%H:%M:%S.%3N%:z")

    # Random log level selection
    levels=("TRACE" "DEBUG" "INFO" "NOTICE" "WARN" "ERROR" "CRITICAL" "ALERT" "EMERGENCY" "FATAL")
    level=${levels[$RANDOM % ${#levels[@]}]}

    # Create labels JSON object
    labels_json="\"labels\":{"
    labels_json+="\"app\":\"logger\","
    labels_json+="\"host\":\"$(hostname)\","
    labels_json+="\"pid\":$$,"
    labels_json+="\"random\":$((RANDOM % 1000))"
    labels_json+="}"

    # Generate random message
    messages=(
        "Processing request"
        "Task completed"
        "Operation failed"
        "Initializing system"
        "Checking permissions"
        "Resource allocated"
        "Connection timeout"
        "Data received"
        "Invalid input"
        "Queue processed"
    )
    message="${messages[$RANDOM % ${#messages[@]}]} [ID: $((RANDOM % 10000))]"

    # Construct single-line JSON
    printf '{"timestamp":"%s","level":"%s",%s,"message":"%s"}\n' \
        "$timestamp" \
        "$level" \
        "$labels_json" \
        "$message"
}

# Handle Ctrl+C
trap 'echo -e "\nLogging stopped. Output: $LOG_FILE"; exit' SIGINT

echo "Logging to $LOG_FILE - Press CTRL+C to stop"
while true; do
    generate_log >> "$LOG_FILE"
    sleep 1
done

Последние строки кода запускают генератор логов в бесконечном цикле — чтобы остановить генератор, нажмите CTRL + C. Вы можете изменить это поведение генератора — например, чтобы задать генерацию логов в течение 1 минуты, замените строки:

while true; do
    generate_log >> "$LOG_FILE"
    sleep 1
done

на строки:

count=0
while [ $count -lt 60 ]; do
    generate_log >> "$LOG_FILE"
    ((count++))
    sleep 1
done

Назначьте файл log_producer.sh исполняемым:
```
sudo chmod +x /usr/local/bin/log_producer/log_producer.sh
```
Запустите генератор логов:
```
sudo /usr/local/bin/log_producer/log_producer.sh
```
Генератор можно запустить в фоновом режиме, добавив к команде знак & — так вы сможете продолжать работать в этой же консоли, не открывая новую для последующих процессов.
```
sudo /usr/local/bin/log_producer/log_producer.sh &
```

После запуска генератор начнет создавать лог-файл /usr/local/bin/log_producer/error_log.log.

Чтобы остановить работу log_producer.sh, нажмите CTRL + C.

Шаг 4. Запуск Fluent Bit для сбора логов

Перед первым запуском fluent-bit в режиме сервиса нужно проверить, нет ли ошибок доступа и корректно ли заполнены файлы настроек. Для этого проверьте работу fluent-bit в следующем порядке:

Запустите fluent-bit в консольном режиме.
Запустите fluent-bit в режиме сервиса.

В дальнейшем вы сможете использовать любой из этих способов.

Запуск в консольном режиме

Запустите fluent-bit в консоли:

sudo /opt/fluent-bit/bin/fluent-bit -c /etc/fluent-bit/fluent-bit.conf

Сообщения такого типа показывают, что данные отправляются успешно:

2025/03/11 15:56:22 send
2025/03/11 15:56:22 0xc00017a010
2025/03/11 15:56:22 logaas send data: {"logs":[{"timestamp":"2025-03-12T15:56:21.975165893Z","level":"EMERGENCY","project_id":"21df218c-931b-4707-8e02-f0498a57e2c9","log_group_id":"80746b7e-efb3-11ef-990d-525356cf44f3","labels":{"app":"logger","host":"myvm","logger":"client_plugin","pid":"61467","random":"646","source":"docker_compose","transport":"log_file"},"message":"Invalid input [ID: 5930]"}]}
2025/03/11 15:56:22 received response body: {
 "errors": {}
}

Чтобы завершить работу fluent-bit, нажмите CTRL + C.

Запуск в режиме сервиса

Запустите fluent-bit для сбора логов как сервис:

sudo systemctl start fluent-bit

Если сервис был запущен ранее, его можно перезапустить, чтобы применились изменения конфигурации:

sudo systemctl restart fluent-bit

Шаг 5. Просмотр логов

Через несколько секунд после отправки логи появятся в сервисе Клиентского логирования.

Вы можете посмотреть логи в лог-группах. Логи можно отфильтровать с помощью языка фильтрующих выражений и выгрузить как файл.

запустите генератор логов в бесконечном цикле, чтобы поддерживать постоянное поступление данных;

выполняйте генерацию логов пакетами — запускайте скрипт многократно с необходимым интервалом.

Это позволяет исключить дублирование записей и поддерживать актуальность передаваемых данных.

После окончания работы

Если виртуальная машина и ее логи стали неактуальными, вы можете удалить их:

Была ли статья полезной ?

Предыдущая статья

Передача логов с виртуальной машины с помощью Fluent Bit logaas plugin

Следующая статья

Передача логов с виртуальной машины с помощью Docker-контейнера плагина Fluent Bit

Поддержка Юридические документы