Apache SkyWalking Nginx Agent

Apache SkyWalking Nginx Agent предоставляет встроенную возможность трассировки для Nginx на основе модуля Nginx LUA.

Этот агент следует протоколу трассировки и заголовков SkyWalking. Он передаёт данные трассировки в APM SkyWalking через протокол HTTP. Все запросы HTTP 1.1, проходящие через Nginx, могут быть собраны этим агентом.

Документация по настройке

Следующая настройка предназначена для OpenResty. Если вам нужен интегрированный шлюз SkyWalking, вы можете перейти к:

1. документации APISIX;
2. документации плагина Kong.

http {
    lua_package_path "/Path/to/.../skywalking-nginx-lua/lib/?.lua;;";

    # Buffer представляет собой регистр информации и очередь завершённого сегмента
    lua_shared_dict tracing_buffer 100m;

    # Init — это таймер установки и сохранения
    # Настройка бесконечного цикла таймера для регистрации и отчёта о трассировке.
    init_worker_by_lua_block {
        local metadata_buffer = ngx.shared.tracing_buffer

        -- Установить имя службы
        metadata_buffer:set('serviceName', 'User Service Name')
        -- Экземпляр означает количество развёртываний Nginx, не означает рабочие экземпляры
        metadata_buffer:set('serviceInstanceName', 'User Service Instance Name')
        -- тип 'boolean', отмечает включение хоста/домена в entrySpan
        metadata_buffer:set('includeHostInEntrySpan', false)
        -- установить ignoreSuffix. Если операция (HTTP URI) entrySpan включает суффиксы из этого набора, этот сегмент будет проигнорирован. Несколько значений должны разделяться запятой (',').
        -- require("skywalking.util").set_ignore_suffix(".jpg,.jpeg,.js,.css,.png,.bmp,.gif,.ico,.mp3,.mp4,.svg")

        -- установить случайное начальное число
        require("skywalking.util").set_randomseed()
        require("skywalking.client"):startBackendTimer("http://127.0.0.1:8080")

        -- Если есть ошибка этой реализации tablepool, мы можем
        -- отключить её таким образом
        -- require("skywalking.util").disable_tablepool()

        skywalking_tracer = require("skywalking.tracer")
    }

    server {
        listen 8090;
        
        location /ingress {
            default_type text/html;

            rewrite_by_lua_block {
                ------------------------------------------------------
                -- ВНИМАНИЕ, это должно быть изменено вручную
                -- Эта переменная представляет адрес вышестоящей логики
                -- Пожалуйста, установите их как имя или DNS-имя логики сервиса
                --
                -- В настоящее время мы не можем иметь реальный сетевой адрес вышестоящего уровня
                ------------------------------------------------------
                skywalking_tracer:start("upstream service")
                -- Если вы хотите добавить корреляционные пользовательские данные в нисходящий сервис
                -- skywalking_tracer:start("upstream service", {custom = "custom_value"})
            }

            -- Целевая вышестоящая служба
            proxy_pass http://127.0.0.1:8080/backend;

            body_filter_by_lua_block {
                if ngx.arg[2] then
                    skywalking_tracer:finish()
                end
            }

            log_by_lua_block {
                skywalking_tracer:prepareForReport()
            }
        }
    }
}

Скачать

Пожалуйста, перейдите на страницу релизов, чтобы загрузить релиз Apache SkyWalking.

Требуется сервер SkyWalking 8 OAP

Настроить среду разработки

Отладка при запуске

Используя /examples/nginx.conf, вы можете запустить Nginx с модулем LUA или OpenResty, например nginx -c. Может быть введён как второй параметр, и тогда они будут переданы нижестоящему сервису. Если позднее можно будет точно определить вышестоящий сервис, сохраните его как nil и вызовите метод inject, когда одноранговый узел (вышестоящий адрес) будет разрешён балансировщиком нагрузки и преобразователем DNS.

• inject, require("skywalking.tracer"):inject(exitSpan, peer, correlation). Внедрить контекст исходящего диапазона и контекст корреляции в носитель, после чего они будут переданы нижестоящей службе. (Начиная с версии 1.0, расширенный API, вызывается при обновлении однорангового узла исходящего диапазона.)

• finish, require("skywalking.tracer"):finish(). Завершить трассировку для этого HTTP-запроса.

• prepareForReport, require("skywalking.tracer"):prepareForReport(). Подготовить завершённый сегмент для дальнейшего отчёта.

API отслеживания на уровне LUA

TracingContext — это входной API для отслеживания на уровне Lua.

• TracingContext.new(serviceId, serviceInstID) — создать активный контекст отслеживания.
• TracingContext.newNoOP() — создать контекст отслеживания без операций.
• TracingContext.drainAfterFinished() — получить сегмент, включающий все завершённые диапазоны.
• TracingContext.inject(exitSpan, peer, correlation) — внедрить контекст исходящего диапазона и контекст корреляции в носитель, а затем они будут переданы нижестоящей службе исходящим HTTP-запросом. (Начиная с версии 1.0, расширенный API, вызываемый при обновлении однорангового узла исходящего диапазона).

Создайте 2 вида диапазонов:

• TracingContext.createEntrySpan(operationName, parent, contextCarrier)
• TracingContext.createExitSpan(operationName, parent, peer, contextCarrier)

Создайте API диапазона 2 видов версии 1:

• TracingContext.createEntrySpan(operationName, parent, contextCarrier)
• TracingContext.createExitSpan(operationName, parent)

Свяжитесь с нами

• Отправьте проблему с [NIGNX-LUA] в качестве префикса заголовка проблемы.
• Список рассылки: dev@skywalking.apache.org. Напишите на dev-subscribe@skywalking.apache.org, чтобы подписаться на список рассылки.
• Присоединитесь к каналу skywalking в Apache Slack. Если ссылка не работает, найдите последнюю на Apache INFRA WIKI.
• Группа QQ: 392443393 (2000/2000, недоступна), 901167865 (доступна).

Руководство по выпуску

Все коммиттеры должны следовать Руководству по выпуску, чтобы опубликовать официальный выпуск.

Лицензия

Apache 2.0