使用 OpenTelemetry 对 OpenResty 进行链路追踪

一、构建 ngx_otel_module 模块

本节将指导您完成 ngx_otel_module 模块的构建。我们将从准备构建环境开始，逐步安装必要的工具和依赖项，获取当前 OpenResty 系统的配置信息，下载匹配的 Nginx 源码，配置编译参数，并最终编译出可用的 ngx_otel_module 模块，为后续的 OpenTelemetry 集成做好准备。您也可以参考 ngx_otel_module 官方说明进行构建，详情请参考 build ngx_otel_module from source。

1. 安装构建工具和依赖项。

   sudo apt update
   
   sudo apt install cmake build-essential libssl-dev zlib1g-dev libpcre3-dev
   
   sudo apt install pkg-config libc-ares-dev libre2-dev # for gRPC

2. 确定 OpenResty 使用的 Nginx 版本和编译配置。

   openresty -V

   以下为输出示例。

   /# openresty -V
   nginx version: openresty/1.25.3.2
   built with OpenSSL 1.1.1w  11 Sep 2023
   TLS SNI support enabled
   configure arguments: --prefix=/usr/local/openresty/nginx --with-cc-opt='-O2 -DNGX_LUA_ABORT_AT_PANIC -I/usr/local/openresty/zlib/include -I/usr/local/openresty/pcre/include -I/usr/local/openresty/openssl111/include' --add-module=../ngx_devel_kit-0.3.3 --add-module=../echo-nginx-module-0.63 --add-module=../xss-nginx-module-0.06 --add-module=../ngx_coolkit-0.2 --add-module=../set-misc-nginx-module-0.33 --add-module=../form-input-nginx-module-0.12 --add-module=../encrypted-session-nginx-module-0.09 --add-module=../srcache-nginx-module-0.33 --add-module=../ngx_lua-0.10.26 --add-module=../ngx_lua_upstream-0.07 --add-module=../headers-more-nginx-module-0.37 --add-module=../array-var-nginx-module-0.06 --add-module=../memc-nginx-module-0.20 --add-module=../redis2-nginx-module-0.15 --add-module=../redis-nginx-module-0.3.9 --add-module=../ngx_stream_lua-0.0.14 --with-ld-opt='-Wl,-rpath,/usr/local/openresty/luajit/lib -L/usr/local/openresty/zlib/lib -L/usr/local/openresty/pcre/lib -L/usr/local/openresty/openssl111/lib -Wl,-rpath,/usr/local/openresty/zlib/lib:/usr/local/openresty/pcre/lib:/usr/local/openresty/openssl111/lib' --with-pcre-jit --with-stream --with-stream_ssl_module --with-stream_ssl_preread_module --with-http_v2_module --with-http_v3_module --without-mail_pop3_module --without-mail_imap_module --without-mail_smtp_module --with-http_stub_status_module --with-http_realip_module --with-http_addition_module --with-http_auth_request_module --with-http_secure_link_module --with-http_random_index_module --with-http_gzip_static_module --with-http_sub_module --with-http_dav_module --with-http_flv_module --with-http_mp4_module --with-http_slice_module --with-http_gunzip_module --with-threads --with-stream --without-pcre2 --with-http_ssl_module

3. 下载对应版本的 Nginx 源码。

   请将 {OPENRESTY_NGINX_VERSION}替换为对应版本 Tag。如要查找 Tag 名称，请访问 https://github.com/nginx/nginx/tags。以 1.25.3.2 版本为例，对应的版本 Tag 为 release-1.25.3。

   git clone https://github.com/nginx/nginx.git
   cd nginx
   git checkout {OPENRESTY_NGINX_VERSION}  # 切换到对应版本Tag

4. 配置 Nginx 编译参数。

   请在 nginx 源码根目录执行以下命令。

   {NGINX_CONFIGURE_ARGUMENTS}为步骤2：确定 OpenResty 使用的 Nginx 版本和编译配置中获取的 configure arguments 内容，并移除与 --add-module相关的参数配置。

   ./auto/configure {NGINX_CONFIGURE_ARGUMENTS} --with-compat 

5. 下载 ngx_otel_module 模块源码。

   cd ..
   git clone https://github.com/nginxinc/nginx-otel.git
   cd /nginx-otel

6. 编译 ngx_otel_module 模块。

   创建并进入 build 目录进行编译，编译完成后会在 build 目录生成 ngx_otel_module.so 文件。

   mkdir build
   cd build
   cmake -DNGX_OTEL_NGINX_BUILD_DIR=/nginx/objs ..
   make

   

二、启用 ngx_otel_module 模块

1. 将ngx_otel_module.so模块文件复制到 nginx modules 目录。

   mkdir -p /usr/local/openresty/nginx/modules/
   cp ngx_otel_module.so /usr/local/openresty/nginx/modules/

2. 配置 nginx.conf。

   为 OpenResty 启用链路追踪，您需要在 Nginx 主配置文件/usr/local/openresty/nginx/conf/nginx.conf中加载 ngx_otel_module 模块并添加配置项。关于 ngx_otel_module 模块的更多参数配置信息，请参见ngx_otel_module 模块文档。

   • 全局配置：为所有 HTTP 请求开启链路追踪。

     load_module modules/ngx_otel_module.so; # 加载 ngx_otel_module
     ...
     http {
         ...
     
         otel_exporter {
             endpoint "${GRPC_ENDPOINT}"; # 前提条件中获取的 gRPC 接入点
             header Authentication "${GRPC_TOKEN}"; # 前提条件中获取的鉴权 Token
         }
     
         otel_trace on;                     # 开启链路追踪
         otel_service_name ${SERVICE_NAME};  # 应用名
         otel_trace_context propagate;         # 向下游服务注入Trace上下文
         ...
     }

   • 单个 Location 配置：为单个 Location 开启链路追踪。

     load_module modules/ngx_otel_module.so; # 加载 ngx_otel_module
     
     ...
     
     http {
     
         otel_exporter {
             endpoint "${GRPC_ENDPOINT}"; # 前提条件中获取的 gRPC 接入点
             header Authentication "${GRPC_TOKEN}"; # 前提条件中获取的鉴权 Token
         }
     
         server {
             listen 127.0.0.1:80;
     
             location /hello {
                 otel_trace         on;             # 只为 127.0.0.1:80/hello 开启链路追踪
                 otel_service_name ${SERVICE_NAME}  # 应用名
                 otel_trace_context propagate;         # 向下游服务注入Trace上下文
     
                 ...
             }
         }
     }

3. 检查 nginx.conf 配置是否正确。

   /usr/local/openresty/nginx/sbin/nginx -t

   预期输出如下，表明配置无误。

   nginx: the configuration file /usr/local/openresty/nginx/conf/nginx.conf syntax is ok
   nginx: configuration file /usr/local/openresty/nginx/conf/nginx.conf test is successful

4. 重载配置。

   # 方式1: 使用 openresty 命令重载配置
   openresty -s reload
   
   # 方式2: 使用 nginx 命令重载配置
   /usr/local/openresty/nginx/sbin/nginx -s reload

三、查看 OpenResty 调用链

完成以上配置并重载后，您可向 OpenResty 发送请求，以生成调用链。然后登录可观测链路 OpenTelemetry 版控制台，查看由 OpenTelemetry 生成的 OpenResty 调用链。

1. 在应用列表页查看 OpenResy 应用。

   

2. 在调用链分析页面查看 OpenResty 的调用链。

   • 查看某个时间段的所有调用链。

   • 查看单个 trace 的完整链路详情。