Skip to main content
Version: 3.7.0

NginxAgent Support Matrix

warning

Only the minimum and maximum minor versions of each major version have been tested and verified.

  • Usage Notes: The reload command is not supported for restarting the agent. If third-party modules are introduced, please verify them yourself (you can use the nginx -V command output for verification, as some third-party modules may modify the core source code, causing adaptation errors)
  • Compilation Notes: The agent is essentially a dynamic extension of nginx and relies on the symbol table exported by nginx. Therefore, the compilation parameters must not include -fvisibility-hidden. Check command: nginx -V | grep fvisibility-hidden
  • Lua Mode: Customers should embed the code according to the documentation and verify in the test environment before going live
  • Secondary Development: Modified nginx source code secondary development versions should be used with caution in production environments and are not within the product support scope. Please verify on your own. The risk is relatively high, so it is recommended to verify in the test environment first.
Itemx86, x86_64aarch64Notes
VersionNginx v1.13.* ~ v1.28.0Nginx v1.13.* ~ v1.28.01.23 [SINCE SmartAgent-6.10.0]
1.24 ~ 25 [SINCE SmartAgent-7.4.0]
1.26 ~ 27 [SINCE SmartAgent-9.2.2]
1.28.0 [SINCE SmartAgent-9.5.1]
Note: The reload command is not supported for restarting the agent
OpenResty v1.13.* ~ v1.19.*, 1.21.4.*, 1.25.3.*, 1.27.1.*OpenResty v1.13.* ~ 1.27.1.*JS Injection Status
1.27.1.x(nginx/v1.27.1) -- Supported
1.25.3.x(nginx/v1.25.3) -- Supported
1.21.4.x(nginx/v1.21.4) -- Supported
1.19.3.x(nginx/v1.19.3) -- Supported
1.17.8.x(nginx/v1.17.8) -- Supported
1.15.8.x(nginx/v1.15.8) -- Supported
1.13.6.x(nginx/v1.13.6) -- Not Supported
Note: The reload command is not supported for restarting the agent
Tengine v2.3.0 ~ v2.3.2, v2.4.0, v3.1.0 [SINCE SmartAgent-8.4.1]Tengine v2.3.0 ~ v2.3.2, Tengine-2.4.0, Tengine-3.1.0 [SINCE SmartAgent-8.4.1]JS Injection Not Supported
Note: The reload command is not supported for restarting the agent
Apisix 2.13.1-
ingress-nginx v0.46.0, 0.49.3 [SINCE SmartAgent-9.2.0]ingress-nginx v0.46.0, 0.49.3 [SINCE SmartAgent-9.2.0]
Application ScenariosStatic Resource ServerStatic Resource Server
http_proxy Reverse Proxyhttp_proxy Reverse Proxy
fastcgi Reverse Proxyfastcgi Reverse Proxy
uwsgi Reverse Proxyuwsgi Reverse Proxy
lua openresty 1.9.15.1-1.19.9.1 (starting from nginx-agent-2.2.0, corresponding to smartagent 6.8.0)-
Containersdockerdocker
cri-ocri-o
podmanpodman
Operating SystemsCentOS 7CentOS 7.3+, CentOS 8+
Red Hat 7UnionTech UOS V20+
Ubuntu 20.04Kylin Server (V10 Tercel)
CentOS 5.11NeoKylin Server (Chromium)
CentOS 6.10openEuler 20.03+
OthersJS Injection (requires specific environment)JS Injection (requires specific environment)

Trace ID Log Append Instructions (Supported since smartagent-7.4.0, nginx-2.6.0)​

Supports appending trace-related information to the access.log. The specific append format depends on the log_format configured in nginx.conf. Trace information will only be written when access.log is enabled for writing (i.e., not using the access_log off; configuration).

Local configuration support added (since nginxagent-3.1.0): The configuration item is the enableTraceInfoAppendToLog parameter in the /opt/bonree/apm/nginx/current/conf/bonree_module.conf file, which is disabled by default (value 0). When enabled (value 1), placeholders will be added to the logs. If the web append switch is off, in non-JSON mode the placeholder will display as "-"; if the web append switch is on, it will display information such as "br.traceId=1d779b52211c8b7538e087ebcfe6f7eb br.spanId=b8ec8707ef69d385 br.traceFlag=01".

Local configuration modifications can be reloaded via the reload command.

Below are log append format examples under different configurations:

1. Unsupported Injection Cases​

Any use of the built-in combined format does not support trace information injection.

access_log logs/access.log combined;

2. Using main Format Log Configuration​

log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                  '$status $body_bytes_sent "$http_referer" '
                  '"$http_user_agent" "$http_x_forwarded_for"';
access_log logs/access.log main;

Example log output with trace information:

192.168.44.1 - - [26/Jan/2024:10:31:14 +0800] "POST /ppinfo.php HTTP/1.1" 200 1916 "-" "PostmanRuntime/7.36.1" "-" "br.traceId=a6a525eecc758d1c1be07e9084cec692 br.spanId=98743c81d74cae8f br.traceFlag=00"

Example log output without trace information:

192.168.44.1 - - [26/Jan/2024:10:31:14 +0800] "POST /ppinfo.php HTTP/1.1" 200 1916 "-" "PostmanRuntime/7.36.1" "-" "-"

3. Using JSON Format Log Configuration (Example 1)​

log_format json escape=json '{"@timestamp":"$time_iso8601",'
                            '"server_addr":"$server_addr",'
                            '"remote_addr":"$remote_addr",'
                            '"scheme":"$scheme",'
                            '"request_method":"$request_method",'
                            '"request_uri": "$request_uri",'
                            '"request_length": "$request_length",'
                            '"uri": "$uri",'
                            '"request_time":$request_time,'
                            '"body_bytes_sent":$body_bytes_sent,'
                            '"bytes_sent":$bytes_sent,'
                            '"status":"$status",'
                            '"upstream_time":"$upstream_response_time",'
                            '"upstream_host":"$upstream_addr",'
                            '"upstream_status":"$upstream_status",'
                            '"host":"$host",'
                            '"http_referer":"$http_referer",'
                            '"http_user_agent":"$http_user_agent" '
                            '  }   ';
access_log logs/access.log json;

Example log output with trace information:

{"@timestamp":"2024-01-26T10:32:59+08:00","server_addr":"192.168.44.185","remote_addr":"192.168.44.1","scheme":"http","request_method":"POST","request_uri": "/ppinfo.php","request_length": "329","uri": "/ppinfo.php","request_time":0.002,"body_bytes_sent":1916,"bytes_sent":2256,"status":"200","upstream_time":"0.002","upstream_host":"0.0.0.0:9000","upstream_status":"200","host":"192.168.44.185","http_referer":"","http_user_agent":"PostmanRuntime/7.36.1" ,"bonree_trace":"br.traceId=0d9ded1fa040e88b918448eb8249c47a br.spanId=9938b7f5ce85c49e br.traceFlag=00"  }

Example log output without trace information:

{"@timestamp":"2024-01-26T10:32:59+08:00","server_addr":"192.168.44.185","remote_addr":"192.168.44.1","scheme":"http","request_method":"POST","request_uri": "/ppinfo.php","request_length": "329","uri": "/ppinfo.php","request_time":0.002,"body_bytes_sent":1916,"bytes_sent":2256,"status":"200","upstream_time":"0.002","upstream_host":"0.0.0.0:9000","upstream_status":"200","host":"192.168.44.185","http_referer":"","http_user_agent":"PostmanRuntime/7.36.1" ,"bonree_trace":""  }

4. Using JSON Format Log Configuration (Example 2)​

log_format json escape=json '{  "s":"sdf2"  }';
access_log logs/access.log json;

Example log output with trace information:

{  "s":"sdf2", "bonree_trace":"br.traceId=9994383053fb010f6920bbc7e1dba7c9 br.spanId=2802794bff373e64 br.traceFlag=00"}

Example log output without trace information:

{  "s":"sdf2", "bonree_trace":""}

5. Using Empty JSON Object Format​

log_format json escape=json '{}';
access_log logs/access.log json;

Example log output with trace information:

{"bonree_trace":"br.traceId=50402067dc69ce99a4747d2251a5c859 br.spanId=1708755a253946b6 br.traceFlag=00"}

Example log output without trace information:

{"bonree_trace":""}

6. Support for Writing to syslog​

access_log syslog:server=unix:/dev/log,tag=nginx,severity=info json;

The log append logic is similar to the aforementioned JSON format, with example output in /var/log/message:

Jan 26 10:44:53 localhost journal: localhost.localdomain nginx: {"@timestamp":"2024-01-26T10:44:53+08:00","server_addr":"192.168.44.185","remote_addr":"192.168.44.1","scheme":"http","request_method":"POST","request_uri": "/ppinfo.php","request_length": "329","uri": "/ppinfo.php","request_time":0.002,"body_bytes_sent":1915,"bytes_sent":2255,"status":"200","upstream_time":"0.002","upstream_host":"0.0.0.0:9000","upstream_status":"200","host":"192.168.44.185","http_referer":"","http_user_agent":"PostmanRuntime/7.36.1" ,"bonree_trace":"br.traceId=70cb58b0947d478cbee54c6e275fcfeb br.spanId=7f50335c7efcaf6c br.traceFlag=00"  }