Skip to main content

Nginx Agent Deployment

The Nginx agent is integrated into UniAgent and supports monitoring Nginx applications.

Compatibility Requirements​

Before installing the agent, please ensure your system meets the following requirements:

  • 64-bit Linux operating system, meeting one of the following:

    • RedHat Enterprise Linux (RHEL) 6.0 or higher
    • CentOS 6.0 or higher
    • SuSE Linux 10.0 or higher
    • Debian 6.0 ("lenny") or higher
    • Ubuntu 9.10 ("Karmic Koala") or higher
    • Any other Linux distribution with kernel version above 2.6.32 and GLIBC version above 2.12.

  • Nginx must meet one of the following:

    • Nginx: 1.11.5 - 1.26.1
    • Openresty: 1.13.6 - 1.25.3
    • Tengine: 2.3.0 - 3.1.0
    • Any product based on Nginx or Openresty, such as apisix.

    The above Nginx versions must be official releases. If the source code has been modified, the agent may not work properly.

    For custom-developed Nginx, you must provide the modified Nginx source code, compilation platform type (currently only x86_64 and aarch64 are supported), compilation options /path/to/nginx -V, and the compiled Nginx signature info strings /path/to/nginx | grep 8,4,8.

Installation​

The Nginx agent is included in the UniAgent package and must be installed with root privileges.

  1. Download the UniAgent installation script and execute it as root:

    sudo sh tingyun-uniagent-<version>.sh

  2. Manually enable the Nginx switch:

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

  3. Restart the Nginx service:

    sudo systemctl restart nginx

Configuration​

The agent configuration file path is /opt/tingyun-oneagent/conf/nginx.conf.

  1. Change the agent log level: modify the agent_log_level field. No need to restart Nginx for the change to take effect.

  2. Capture HTTP request headers: modify the capture_header field. Currently, only one HTTP header can be configured. No need to restart Nginx for the change to take effect.

  3. Change Nginx application naming mode: modify the naming_mode field. No need to restart Nginx for the change to take effect.

    Supported naming modes:

    0 - server_name:port
    1 - server_name
    2 - http_host:port
    3 - http_host
    4 - host IP:port
    5 - host IP

    Where:

    • server_name refers to the server name specified in the Nginx configuration file.
    • http_host refers to the domain in the HTTP request; if not present, the client IP is used.
    • host IP refers to the value of the host_ip field in the current configuration file, which defaults to the current host or Pod IP, but can be manually set.

    ⚠️ If a server block in the Nginx configuration specifies multiple server_names, e.g.:

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

    The agent can only obtain the first name. For the above, only www.test.com will be used. If naming_mode is set to 0, requests for all three domains will be aggregated under www.test.com. To split different domains, set naming_mode to 2, so requests are named by domain:port.

Enable Web Frontend Performance Analysis​

UniAgent 2.5.4.0 and above support automatic JS agent injection into HTML pages via the Nginx agent to collect Web frontend performance data.

To enable, go to "User Experience" -> "Web" -> "Applications", click "Add Application", enter the application name, select "APM Injection" as the embedding method, select the corresponding backend application for Nginx, and click enable.

In the following scenarios, JS agent injection is not possible:

  • Requests not initiated by browsers, such as those from Curl, Wget, or HttpClient.
  • Backend application responses to Nginx are compressed.
  • Content-Type is not text/html.
  • Response status code is not 200.
  • JS injection position exceeds 64K.

FAQ​

How to view Nginx agent logs​

  • For UniAgent 2.2.2.0 and below, the Nginx agent does not have a separate log file; logs are output to the Nginx error log. Please check the Nginx error log path.
  • For UniAgent 2.3.0.0 and above, the Nginx agent log file is at /opt/tingyun-oneagent/logs/agent/nginx.log.

Set agent_log_level in /opt/tingyun-oneagent/conf/nginx.conf to DEBUG to output debug-level logs. Changing the log level does not require restarting Nginx; it takes effect within about 1 minute.

To search Nginx logs:

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

How to confirm if the Nginx agent is loaded successfully?​

  1. Check agent version and support list:
    • Check UniAgent version:
    cat /opt/tingyun-oneagent/Version
    • Check supported Nginx versions:
    grep nginx /opt/tingyun-oneagent/conf/interceptor.conf
  2. Check if UniAgent service is running: 
    sudo systemctl status tingyun-oneagent
    The service status should be Active: active (running). 
    sudo cat /etc/ld.so.preload
    The content should be /lib64/libinterceptor.so.
  3. Check if the Nginx agent switch is enabled: 
    grep nginx_enabled /opt/tingyun-oneagent/conf/interceptor.conf
    Ensure nginx_enabled is true. If not, modify and restart Nginx.
  4. Check if the Nginx agent is loaded:
    • View Nginx process list:
    ps -ef | grep nginx
    • Find a Nginx process PID and run:
    sudo grep "tingyun" /proc/<nginx_pid>/maps
    If you see entries like agent/nginx_xxx/lib/tingyun_nginx_module, the agent is loaded successfully. If not, check if nginx_enabled=true is set in interceptor.conf. If enabled but still not loaded, the Nginx version or compilation options may not be supported. Check the load log: 
    grep nginx /opt/tingyun-oneagent/logs/oneagent/preload.log
    If you do not know the actual Nginx path, run: 
    sudo readlink -f /proc/<nginx_pid>/exe
    • Check Nginx version:
    <nginx_path> -v
    • Check Nginx compilation options:
    <nginx_path> -V
    • Check Nginx signature info:
    strings <nginx_path> | grep 8,4,8
    • Check if the corresponding so file exists; if not, it is not supported.