Search…
NGINX
The topic details steps to install and configure Traceable's NGINX tracing agent along with the supported NGINX version. Traceable supports both NGINX enterprise and NGINX community editions.
Traceable provides an NGINX dynamic tracing agent that you can deploy for monitoring and blocking of clients. The NGINX plugin is agnostic to the type of NGINX deployment, for example, your NGINX could be deployed as a reverse proxy or as a load balancer.
The following diagram shows an example of NGINX plugin deployment:
The plugin connects to the Traceable Platfom Agent (TPA). The TPA further sends the data to Traceable’s platform for further analysis. The following flow chart summarises the entire deployment steps:

Support

Traceable supports the following open-source versions of NGINX with its NGINX plugin:
  • 1.11.x versions - 1.11.10, 1.11.11, 1.11.12, 1.11.13
  • 1.12.x versions - 1.12.0,1.12.1,1.12.2
  • 1.13.x versions - 1.13.0, 1.13.1, 1.13.2, 1.13.3, 1.13.4, 1.13.5, 1.13.6, 1.13.7, 1.13.8, 1.13.9, 1.13.10, 1.13.11, 1.13.12
  • 1.14.x versions - 1.14.0,1.14.1,1.14.2
  • 1.15.x versions - 1.15.0,1.15.8
  • 1.16.x versions - 1.16.0, 1.16.1
  • 1.17.x versions - 1.17.0, 1.17.1, 1.17.2, 1.17.3, 1.17.4, 1.17.5, 1.17.6, 1.17.7, 1.17.8, 1.17.9, 1.17.10
  • 1.18.x versions - 1.18.0
  • 1.19.x versions - 1.19.0
  • 1.20.x versions - 1.20.0, 1.20.1
  • 1.21.x versions - 1.21.0, 1.21.1

Prerequisites

Complete the following prerequisites before proceeding to install the NGINX plugin:

Setup

Verify

1
# nginx -V
2
nginx version: nginx/1.19.0
3
built by gcc 8.3.0 (Debian 8.3.0-6)
4
built with OpenSSL 1.1.1d 10 Sep 2019
5
TLS SNI support enabled
Copied!
Verify whether your NGINX deployment is compiled with --with-compat argument. To verify, enter the following command:
1
nginx -V
Copied!
  • If the --with-compat flag is not displayed in the output, visit Compiling nginx
  • Take note of the value for --modules-path. For example, /usr/lib/nginx/modulesand--modules-path=/usr/lib64/nginx/modules

Download

1
wget https://downloads.traceable.ai/#agent/nginx/latest/...
Copied!
Visit https://downloads.traceable.ai. Navigate to /agent/nginx/latest and search for your NGINX version. If you are running Alpine, download that version. Otherwise, select the one prefixed with Linux.

Untar

Enter the following command to untar the downloaded file:
1
tar -xvzf <filename>.so.tgz
Copied!
After you untar the file, you would get the following two files:
  • ngx_http_traceableai_module.so - This is the dynamic module file.
  • libtraceable.so- NGINX's blocking feature is dependent on this library file.
Blocking is not supported with NGINX on Alpine, and this file is not included in the Alpinetgz.

Copy

Enter the following command to copy the *.so files to the modules directory:
1
sudo cp *.so /path/to/modules
Copied!
You can find the path to your modules directory by running thenginx -V command. For example, the path could be: --modules-path=/usr/lib64/nginx/modules

Configure

Edit

You can use Vi editor or any editor of your choice to edit the nginx.conf file. The following command uses Vi editor:
1
sudo vi /etc/nginx/nginx.conf
Copied!
Add the load_module directive to the top of the file (after the user directive):
1
load_module modules/ngx_http_traceableai_module.so;
Copied!
Add the traceableai directive inside the http block. Replace YOUR-SERVICE-NAME with the service name from your environment.
1
traceableai {
2
service_name nginx-YOUR-SERVICE-NAME;
3
collector_host <collector_hostname>; # NOTE: prefixing with protocol (http[s]) will fail silently. Spans will not show in Traceable
4
collector_port 9411;
5
blocking on; # To enable blocking
6
opa_server http://<opa_hostname>:8181/;
7
opa_log_dir /tmp/;
8
}
Copied!
Add the opentracing and opentracing_propagate_context after the traceableai block. For more information on opentracing_propagate_context, see Broken Correlation.
1
...
2
load_module modules/ngx_http_traceableai_module.so; # 1
3
...
4
server {
5
http {
6
traceableai { # 2
7
service_name nginx-YOUR-SERVICE-NAME; # 3
8
collector_host <collector_hostname>; # 4
9
collector_port 9411;
10
blocking on;
11
opa_server http://<opa_hostname>:8181/; # 5
12
opa_log_dir /tmp/;
13
}
14
15
opentracing on; # 6
16
opentracing_propagate_context; # 7
17
18
}
19
20
}
21
...truncated nginx.conf...
Copied!

Optional

It is possible to disable tracing for individual location directives. Do so by defining opentracing off;inside the NGINX config file which contains the location to be excluded from tracing.
1
location /static {
2
# disable monitoring for the /static location
3
opentracing off;
4
proxy_pass http://static-content:8080;
5
}
6
location /api{
7
proxy_pass http://apiserver:9090;
8
}
Copied!
Following is a sample nginx.conf file:
1
user nginx;
2
worker_processes auto;
3
4
error_log /var/log/nginx/error.log notice;
5
pid /var/run/nginx.pid;
6
7
load_module modules/ngx_http_traceableai_module.so;
8
9
events {
10
worker_connections 1024;
11
}
12
13
http {
14
traceableai {
15
service_name "nginx-traceableai";
16
collector_host "localhost";
17
collector_port 9411;
18
blocking on;
19
blocking_log_to_console on;
20
opa_server http://localhost:8181/;
21
config_endpoint localhost:5441;
22
config_polling_period 10;
23
}
24
25
opentracing on;
26
opentracing_trace_locations on;
27
28
include /etc/nginx/mime.types;
29
default_type application/octet-stream;
30
31
log_format main '$remote_addr - $remote_user [$time_local] "$request" '
32
'$status $body_bytes_sent "$http_referer" '
33
'"$http_user_agent" "$http_x_forwarded_for"';
34
35
access_log /var/log/nginx/access.log main;
36
sendfile on;
37
keepalive_timeout 65;
38
39
server {
40
listen 80;
41
server_name localhost;
42
43
location / {
44
root /usr/share/nginx/html;
45
index index.html index.htm;
46
}
47
48
error_page 500 502 503 504 /50x.html;
49
location = /50x.html {
50
root /usr/share/nginx/html;
51
}
52
}
53
54
include /etc/nginx/conf.d/*.conf;
55
}
Copied!

Reload

Enter the following command to reload NGINX:
1
sudo nginx -s reload
Copied!

Definitions

  • traceableai syntax - traceableai{} context - http
  • service_name syntax - service_name <identifiable_name_of_the_service> default - nginx context - traceableai Give a meaningful name of service with which you can identify it on Traceable’s Dashboard.
  • collector_host syntax - collector_host <hostname_of_collector> default - collector.traceableai context - traceableai
  • collector_port syntax - collector_port <port_of_collector> default - 9411 context - traceableai
  • blocking syntax - opa on|off default - off context - traceableai By default OPA is disabled. OPA is required if you wish to enable blocking in NGINX deployment.
  • opa_server syntax - opa_server <opa_server_address default - http://opa.traceableai:8181 context - traceableai URL on which OPA service is deployed for the NGINX module to communicate.
  • opentracing syntax - opentracing on|off default - off context - http, server,location` Enables or disables OpenTracing for NGINX requests.
  • opentracing_propagate_context syntax - opentracing_propagate_context context - http, server,location` Opentracing_propagate_context propagates the active span context for upstream requests. For more information, see Inject and Extract.

Verification

  1. 1.
    Exercise the applications routing through NGINX
  2. 2.

Generate traffic (optional)

Traceable discovers APIs or displays metrics based on the user traffic. You need to proxy your application through NGINX. For example, if you have an application running on http://YourApplication.com:9191/order then add the following block to the /etc/nginx/conf.d/default.conf file.
1
location /order {
2
proxy_pass http://YourApplication.com:9191/order;
3
# set any proxy header you want to pass on
4
}
Copied!
After configuring the above, you can access your application from http://nginx-proxy.YourApplication.com/order. This assumes that NGINX proxy that is installed on nginx-proxy.YourApplication.com is configured to accept traffic on port number 80. You can also use HTTPS instead of HTTP.

Troubleshooting

No Traces in Traceable

Tail the NGINX error logs:
1
sudo tail -f /var/log/nginx/error.log
Copied!

Broken correlation

Identify all thelocationblocks in your NGINX configuration files. If they have the proxy_set_headerdirective defined, you will need to addopentracing_propagate_context to these location blocks. Check for anyinclude statements that could potentially be including that directive. See the info message below.
opentracing_propagate_context internally uses proxy_set_header to pass the request context to upstream. proxy_set_header directives are inherited from the previous configuration level if and only if there are no proxy_set_header directives defined on the current level.
When the requests are proxied to upstream, but:
-- opentracing_propagate_context has been defined in http, or server block, AND
-- A proxy_set_header exists in the location block, then the request context is not propagated upstream.
If proxy_set_header exists inside the location block, then define opentracing_propagate_context in the location block only.
Last modified 2mo ago