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，请求会按照域名:端口进行命名。

开启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。

results matching ""

    No results matching ""