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.confagent_log_level日志级别设置为DEBUG可以输出调试级别的日志。更改日志级别开关不需要重启Nginx,等待1分钟后会自动生效。

搜索Nginx日志:

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

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

  1. 首先请确认UniAgent服务是否正常工作。

     sudo systemctl status tingyun-oneagent
    

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

     sudo cat /etc/ld.so.preload
    

    内容应该为 /lib64/libinterceptor.so

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

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

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

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

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

    ps -ef | grep nginx
    

    找到任意一个Nginx的进程id,运行命令:

    sudo grep "tingyun" /proc/[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版本:

    /path/to/nginx -v
    

    输出应该类似如下内容:

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

    确认Nginx编译选项:

    /path/to/nginx -V
    

    输出应该类似如下内容:

    [tingyun@bogon ~]$ 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 /path/to/nginx | grep 8,4,8
    

    输出应该类似如下内容:

    [tingyun@bogon ~]$ strings /usr/sbin/nginx | grep 8,4,8
    8,4,8,0010111111010111001110111111111110
    
  4. 确认是否有崩溃信息。

    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
    

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

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

    /opt/tingyun-oneagent/conf/nginx.confagent_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 failopen socket failconnect to daemon failsend 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 ""