Nginx探针部署

UniAgent中集成了Nginx探针，支持监控Nginx应用。

兼容性要求

安装探针之前，请确保您的系统满足如下这些条件：

• Linux 64位操作系统，满足以下列表条件之一：

  • RedHat Enterprise Linux (RHEL) 6.0 或更高版本
  • CentOS 6.0 或更高版本
  • SuSE Linux 10.0或更高版本
  • Debian 6.0 ("lenny") 或更高版本
  • Ubuntu 9.10 ("Karmic Koala") 或更高版本
  • 任何其他内核版本高于2.6.32，GLIBC版本高于2.12的Linux发行版。

• Nginx需要满足以下条件之一：

  • Nginx ：1.11.5 - 1.26.1
  • Openresty ：1.13.6 - 1.25.3
  • Tengine ：2.3.0 - 3.1.0
  • 任何以Nginx或Openresty为基础组件的产品，例如apisix。

  以上Nginx版本必须为官方发布版本，如果在官方版本基础上修改过源码，会造成探针无法正常工作。

  如果要适配二次开发过的Nginx，必须提供二次开发后的Nginx源码、编译平台类型(目前仅支持x86_64和aarch64 两种，即amd64还是arm64)、编译选项/path/to/nginx -V和编译后的Nginx签名信息strings /path/to/nginx | grep 8,4,8

安装

Nginx探针集成在了UniAgent包中，需要以root权限安装。

1. 下载UniAgent安装脚本并以root权限执行。

sudo sh tingyun-uniagent-版本.sh

2. 手工开启Nginx开关。

sudo sed -i -e "s/nginx_enabled.*/nginx_enabled=true/" /opt/tingyun-oneagent/conf/interceptor.conf

3. 重启Nginx服务。

sudo systemctl restart nginx

配置

探针配置文件路径为/opt/tingyun-oneagent/conf/nginx.conf。

1. 修改探针日志级别：修改agent_log_level字段，修改后不需要重启Nginx应用即可生效。

2. 捕捉HTTP请求头：修改capture_header字段，目前仅支持配置最多一个HTTP头，修改后不需要重启Nginx应用即可生效。

3. 修改Nginx应用命名方式：修改naming_mode字段，修改后不需要重启Nginx应用即可生效。

   支持以下几种命名方式：

   0 - 按server_name:port命名
   1 - 按server_name命名
   2 - 按http_host:port命名
   3 - 按http_host命名
   4 - 按主机IP:port命名
   5 - 按主机IP命名

   其中：

   • server_name指的是Nginx自身配置文件内指定的server名称。
   • http_host指的是HTTP请求内的域名，如果没有域名则取访问端的IP地址。
   • 主机IP指的是当前配置文件内的host_ip字段的内容，host_ip字段默认为当前主机或Pod的IP地址，也可手工修改为其他想要的内容。

   ⚠️ 当Nginx配置中一个server段server_name指定了多个名称时，例如以下配置：

   server {
       listen       80;
       server_name  www.test.com www1.test.com www2.test.com;
       root         /usr/share/nginx/html;
   }

   探针只能获取到第一个名称，对于上述例子，只能获取到www.test.com, 即当naming_mode配置为0时，www.test.com、 www1.test.com、 www2.test.com 3个域名产生的请求均汇总在www.test.com之下

   如果想将不同的域名拆开，请将naming_mode配置为2，请求会按照域名:端口进行命名。

功能范围

• 仅支持采集 http/https 协议请求的性能数据
• 不支持采集 gRPC, WebSocket, SMTP, IMAP, POP3 协议请求的性能数据
• 不支持采集 TCP/UDP 层代理的性能，例如 MySQL、Redis、SMTP 等
• 不支持的功能：自定义嵌码、用户溯源、自定义事务命名

开启Web前端性能分析功能

UniAgent 2.5.4.0及以上版本支持通过Nginx探针自动对html页面嵌入JS探针，采集Web前端性能数据。

开启流程为在 "用户体验" -> "Web" -> "应用" 页面点击 "添加应用" 按钮，录入页面应用名称，嵌码方式选择 "APM注入", 选择Nginx对应的后端应用，点击启用即可。

在以下场景，无法嵌入JS探针：

• 非浏览器发起的请求，例如Curl、Wget等工具发起的请求，上游应用利用HttpClient发起的请求

• 后端应用返回给Nginx时内容为压缩时

• Content-Type不是text/html格式时

• 响应状态码不为200时

• JS可嵌码位置超过64K时

常见问题

如何查看Nginx探针的日志

• UniAgent 2.2.2.0及以下版本，Nginx探针没有独立的日志文件，探针将日志输出到Nginx的error日志内，请确认Nginx的error日志路径位置。

• UniAgent 2.3.0.0及以上版本，Nginx探针日志文件位置为/opt/tingyun-oneagent/logs/agent/nginx.log。

将 /opt/tingyun-oneagent/conf/nginx.conf 中agent_log_level日志级别设置为DEBUG可以输出调试级别的日志。更改日志级别开关不需要重启Nginx，等待1分钟后会自动生效。

搜索Nginx日志：

tail -f /path/to/nginx/logs/error.log | grep tingyun

如何确认Nginx探针是否成功加载？

1. 确认探针版本及支持列表

   确认UniAgent版本的版本：

   cat /opt/tingyun-oneagent/Version

   确认UniAgent支持的nginx版本，下面列表为当前探针的支持列表：

   grep nginx /opt/tingyun-oneagent/conf/interceptor.conf

2. 确认UniAgent服务是否正常工作。

   sudo systemctl status tingyun-oneagent

   UniAgent服务状态应该为Active: active (running) 。

   sudo cat /etc/ld.so.preload

   内容应该为 /lib64/libinterceptor.so。

3. 确认Nginx探针开关是否开启。

   grep nginx_enabled /opt/tingyun-oneagent/conf/interceptor.conf

   确认nginx_enabled开关是否为true，如果不为true请修改并重启Nginx。

4. 确认Nginx探针是否加载。

   运行命令查看Nginx进程列表：

   ps -ef | grep nginx

   找到任意一个Nginx的进程id，运行命令：

   sudo grep "tingyun" /proc/nginx进程的pid/maps

   如果存在agent/nginx_xxx/lib/tingyun_nginx_module字样，说明Nginx探针加载成功。

   [tingyun@bogon ~]$ sudo grep "tingyun" /proc/23241/maps
   7f0467f02000-7f0467f05000 r-xp 00000000 fd:01 34581021  /opt/tingyun-oneagent/agent/nginx_2.0.0/lib/tingyun_nginx_module-1.13.10-1111111111.so
   7f0467f05000-7f0468104000 ---p 00003000 fd:01 34581021  /opt/tingyun-oneagent/agent/nginx_2.0.0/lib/tingyun_nginx_module-1.13.10-1111111111.so
   7f0468104000-7f0468105000 rw-p 00002000 fd:01 34581021  /opt/tingyun-oneagent/agent/nginx_2.0.0/lib/tingyun_nginx_module-1.13.10-1111111111.so

   如果没有上述内容，说明探针未成功加载，请确认interceptor.conf中 nginx_enabled=true 是否打开。

   如果开关已打开，可能是Nginx版本或编译选项没有在探针适配范围内，请执行以下命令查看加载日志：

   grep nginx /opt/tingyun-oneagent/logs/oneagent/preload.log

   如果不清楚nginx实际路径，请执行 sudo readlink -f /proc/nginx进程的pid/exe

   确认Nginx版本：

   nginx实际路径 -v

   输出应该类似如下内容：

   [tingyun@bogon ~]$ /usr/sbin/nginx -v
   nginx version: nginx/1.14.1

   确认Nginx编译选项：

   nginx实际路径 -V

   输出应该类似如下内容：

   [tingyun@bogon ~]$ /usr/sbin/nginx -V
   nginx version: nginx/1.14.1
   built by gcc 8.2.1 20180905 (Red Hat 8.2.1-3) (GCC) 
   built with OpenSSL 1.1.1 FIPS  11 Sep 2018 (running with OpenSSL 1.1.1k  FIPS 25 Mar 2021)
   TLS SNI support enabled
   configure arguments: --prefix=/usr/share/nginx --with-file-aio --with-ipv6 --with-http_ssl_module --with-http_v2_module --with-http_realip_module --with-http_dav_module --with-http_gzip_static_module 

   确认Nginx签名信息：

   strings nginx实际路径 | grep 8,4,8

   输出应该类似如下内容：

   [tingyun@bogon ~]$ strings /usr/sbin/nginx | grep 8,4,8
   8,4,8,0010111111010111001110111111111110

   确认对应的so是否存在，如果不存在说明没有适配:

   sign=$(strings nginx实际路径 | grep 8,4,8, | cut -c 29-38)
   echo "sinature: ${sign}"
   ls /opt/tingyun-oneagent/agent/nginx_$(cat /opt/tingyun-oneagent/agent/nginx_version)/lib/tingyun_nginx_module-*-${sign}.so

5. 确认是否有崩溃信息。

   UniAgent 2.2.2.0及以下版本:

   cat /opt/tingyun-oneagent/logs/agent/nginx.log

   UniAgent 2.3.0.0及以上版本:

   cat /opt/tingyun-oneagent/logs/agent/nginx.crash

   如果有内容则说明探针发生了崩溃，请将此文件内容取回。

6. 确认Nginx探针工作情况。

   将 /opt/tingyun-oneagent/conf/nginx.conf 中agent_log_level日志级别设置为DEBUG。

   更改此开关不需要重启Nginx，等待1分钟后会自动生效。

   UniAgent 2.2.2.0及以下版本, 确认nginx的error.log日志路径，查看nginx的error.log日志:

   tail -f /path/to/nginx/logs/error.log | grep tingyun

   UniAgent 2.3.0.0及以上版本:

   tail -f /opt/tingyun-oneagent/logs/agent/nginx.log

   • 如果日志内出现 app name is null，说明获取应用名失败，探针默认从server name获取应用名，当nginx没有配置server name时，会出现上述现象，此时需要更改 /opt/tingyun-oneagent/conf/nginx.conf 中的naming_mode为2或4。

   • 如果日志内出现 create io thread fail 或 open socket fail 或 connect to daemon fail 或 send to daemon fail说明和collector通信失败。

   • 如果日志仅有大量 send cmd to daemon，说明collector和DC通讯异常，请检查collector配置，查看/opt/tingyun-oneagent/logs/agent/daemon.log日志。

   • 如果日志有recv config，说明collector和DC通讯正常。

   • 如果日志有recv config: enabled=true 说明探针开关正常。

   • 当收到HTTP请求阶段会打印日志upstream header: X-Tingyun。

   • 在收到后端其他应用探针返回的HTTP头时会打印日志upstream response: X-Tingyun-Data。

   • 当返回HTTP响应阶段，如果有跨应用标记会打印日志outbound header: X-Tingyun-Data。

   • 如果请求仅在nginx本地处理，不转发到upstream，探针不会采集此请求的trace，例如nginx的图片文件，会打印日志request is static。

   • 当发送trace数据时，会打印日志send trace to daemon。

   • 如果发送trace数据失败，会打印日志send trace to daemon fail。