Модуль ngx_http_idgen_module

Модуль ngx_http_idgen_module предоставляет генерацию ULID, UUIDv4 и UUIDv7 на основе стандартного request_id nginx.

Модуль разработан с учетом практик хранения логов в ClickHouse. Первоначально предполагалось реализовать только UUIDv7, поскольку он позволяет эффективно задействовать индексы пропуска данных типа MinMax. В процессе разработки для тестирования была добавлена поддержка UUIDv4, а позже в документации ClickHouse была обнаружена информация о ULID.

Таким образом, при использовании ClickHouse для хранения логов с временной партицией, применение MinMax-индекса по полям ULID или UUIDv7 обеспечит высокую эффективность поиска по id.

Как оказалось, MinMax в ClickHouse работает коряво с форматом UUID, поэтому для получения преимуществ придется использовать текстовые форматы полей (как для ULID так и для UUIDv7)

Due to historical reasons, UUIDs are sorted by their second half.

https://clickhouse.com/docs/sql-reference/data-types/uuid

Преимущества идентификаторов

ULID (Universally Unique Lexicographically Sortable Identifier)

• Сортируемость: Сортировка по времени создания
• Хронология: Встроенная временная метка с точностью до миллисекунд
• Уникальность: 128-битная случайность с временной компонентой
• Читаемость: Безопасные символы для URL и файловых систем

UUIDv4

• Стандартизация: Соответствие RFC 4122
• Случайность: 122 бита криптографической случайности
• Независимость: Не требует синхронизации времени

UUIDv7

• Сортируемость: Сортировка по времени создания
• Хронология: Встроенная временная метка с точностью до миллисекунд
• Совместимость: Соответствие RFC 9562
• Эффективность: Компромисс между временем и случайностью

Преимущества реализации

• Детерминированность: Генерация основана на стандартном request_id
• Производительность: Минимальные накладные расходы

Переменные

$request_ulid

Содержит ULID Формат: 01K5GG7A0YB93D3413W1X4F167 (26 символов)

$request_uuidv4

Содержит UUIDv4 Формат: 5a46d190-23e0-4a47-84c7-00211a09229b (36 символов)

$request_uuidv7

Содержит UUIDv7 Формат: 01996103-a81e-7a47-84c7-00211a09229b (36 символов)

Пример конфигурации

http {
    log_format json_combined '{'
        '"time": "$time_iso8601",'
        '"remote_addr": "$remote_addr",'
        '"request_id": "$request_id",'
        '"ulid": "$request_ulid",'
        '"uuidv4": "$request_uuidv4",'
        '"uuidv7": "$request_uuidv7",'
        '"status": "$status"'
    '}';

    access_log logs/access.json json_combined;

    server {
        listen 7080;
        server_name localhost;
        server_tokens off;

        location / {
            add_header X-ULID $request_ulid;
            add_header X-UUIDv4 $request_uuidv4;
            add_header X-UUIDv7 $request_uuidv7;
            add_header X-REQ-ID $request_id;
            add_header X-connection-time $connection_time;
            add_header X-msec $msec;

            return 200;
        }
    }

}

Особенности реализации

Генерация идентификаторов

Модуль использует стандартный request_id nginx в качестве источника случайности:

• Если request_id доступен (32 hex символа) — используется для генерации
• Если request_id недоступен — используются нули для демонстрации

Производительность

• Идентификаторы генерируются лениво (по первому обращению)
• Результаты кэшируются в контексте запроса
• Минимальное использование памяти

Требования

• Nginx: 1.11.0 или выше
• Система: поддержка 64-битных
• Конфигурация: работоспособность request_id