NGINX community version

Traceable supports the following operating systems:

• Amazon Linux 2

• CentOS 7 and 8

• Ubuntu 18.0.4 and Ubuntu 20.0.4

• Debian 10

---

NGINX community support

NGINX community major version	Minor versions
1.11.x	1.11.10, 1.11.11, 1.11.12, 1.11.13
1.12.x	1.12.0,1.12.1,1.12.2
1.13.x	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	1.14.0,1.14.1,1.14.2
1.15.x	1.15.0,1.15.8
1.16.x	1.16.0, 1.16.1
1.17.x	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	1.18.0
1.19.x	1.19.0
1.20.x	1.20.0, 1.20.1
1.21.x	1.21.0, 1.21.1, 1.21.3, 1.21.4, 1.21.5, 1.21.6
1.22.x	1.22.1
1.23.x	1.23.2, 1.23.3, 1.23.4
1.24.x	1.24.0
1.25.x	1.25.0, 1.25.1, 1.25.2, 1.25.3, 1.25.4, 1.25.5
1.26.x	1.26.1, 1.26.2
1.27.x	1.27.0, 1.27.1, 1.27.2

Refer to the NGINX 0.1.75 release notes to view NGINX agent support for CentOS 7 and CentOS 8.

---

The installation topic is divided into:

• Individual OS-specific instructions

• Verification

• Upgrade

• Uninstall

---

Validations script

Traceable provides a NGINX validation script. The script validates whether you are running a version of NGINX that is supported by Traceable. Traceable provides:

• yum package for the official NGINX CentOS and EPEL repos.

• apt packages for the official NGINX Ubuntu repos.

Enter the following command:

curl -L https://downloads.traceable.ai/install/nginx/validate.sh | sh -

---

Amazon Linux 2

Installing Traceable’s Tracing agent on NGINX community version running on Amazon Linux 2 consists of the following steps:

1. Check NGINX repository

2. Install Traceable’s Tracing agent

3. Edit nginx.conf file

4. Reload NGINX

Step 1 - Check NGINX repository

Enter the following command to check from which repository NGINX was installed.

yum info nginx | grep "From repo"

Step 2 - Install NGINX tracing agent

Complete the following steps to install Traceable NGINX Tracing agent:

1. Set up the yum repository. You might have already done this as part of setting up traceable-agent. For more information, see Setup the repository in Virtual machine topic.

2. Install the Tracing agent. Replace "NN.N"with your NGINX version.

   • **Non-EPEL release: ** Enter the following command to install NGINX module:

     ActionScript

     sudo yum install nginx-module-traceable-1.NN.N

   • **EPEL release: ** Enter the following command to install NGINX module:

     ActionScript

     sudo yum install nginx-module-traceable-epel-1.NN

Step 3 - Edit the configuration file

Edit your nginx.conf file, for example, /etc/nginx/nginx.conf. Complete the following steps:

1. Add the load module directive after pid /run/nginx.pid

   • **Non-EPEL release: **

     load_module modules/ngx_http_traceableai_module.so;

   • EPEL release:

     load_module /usr/lib64/nginx/modules/ngx_http_traceableai_module.so;

2. Add the following to the nginx.conf file in the http block above the include /etc/nginx/conf.d/*.conf

traceableai {
    service_name nginx;
    collector_host localhost;
    collector_port 9411;
    blocking on;
    config_endpoint localhost:5441;
  }
  # enable monitoring for all requests.
  opentracing on;
  # propagate request context to upstream services
  opentracing_propagate_context;

If your location block has proxy_set_header set, add opentracing_propagate_context to the location block, else add opentracing_propagate_context to the http block as shown in step 2 above.

Optional - Add custom error code

You can add a custom error code in 4xx series as response status code when a request gets blocked. You can configure this in the nginx.conf file by setting blocking_status_code field in the traceableai section. The default value is set to 403. The following is an example snippet, with the last line showing the blocking_status_code value set to 472.

traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }

Content capture

You can configure the type of content you wish to capture. Configure capture_content_types inside the traceableai section. Capturing of the following content types is supported:

• xml

• json

• grpc

• x-www-form-urlencoded

If you wish to capture XML json, specify the directive as capture_content_types xml json. If the directive is not specified, Traceable by default captures json, grpc, and x-www-form-urlencoded content as these are the most common content types.

traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on; 
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        # capture content type
        capture_content_types xml json
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }

Step 4 - Reload NGINX

Enter the following command to reload NGINX configuration:

sudo nginx -s reload

Verify whether the installation was successful.

---

CentOS

Installing Traceable’s Tracing agent on NGINX community version running on CentOS consists of the following steps:

1. Check NGINX repository

2. Install Traceable’s Tracing agent

3. Edit nginx.conf file

4. Reload NGINX

Step 1 - Check NGINX repository

Enter the following command to check from which repository NGINX was installed.

yum info nginx | grep "From repo"

Step 2 - Install NGINX tracing agent

Complete the following steps to install Traceable NGINX Tracing agent:

1. Set up the yum repository. You might have already done this as part of setting up traceable-agent. For more information, see Setup the repository in Virtual machine topic.

2. Install the Tracing agent. Replace "NN.N"with your NGINX version.

   1. **Non-EPEL release: ** Enter the following command to install NGINX module:

      ActionScript

      sudo yum install nginx-module-traceable-1.NN.N

   2. **EPEL release: ** Enter the following command to install NGINX module:

      ActionScript

      sudo yum install nginx-module-traceable-epel-1.NN

Step 3 - Edit the configuration file

Edit your nginx.conf file, for example, /etc/nginx/nginx.conf. Complete the following steps:

1. Add the load module directive after pid /run/nginx.pid

   • **Non-EPEL release: **

     load_module modules/ngx_http_traceableai_module.so;

   • EPEL release:

     load_module /usr/lib64/nginx/modules/ngx_http_traceableai_module.so;

2. Add the following to the nginx.conf file in the http block above the include /etc/nginx/conf.d/*.conf

traceableai {
    service_name nginx;
    collector_host localhost;
    collector_port 9411;
    blocking on;
    config_endpoint localhost:5441;
  }
  # enable monitoring for all requests.
  opentracing on;
  # propagate request context to upstream services
  opentracing_propagate_context;

If your location block has proxy_set_header set, add opentracing_propagate_context to the location block, else add opentracing_propagate_context to the http block as shown in step 2 above.

Optional - Add custom error code

You can add a custom error code in 4xx series as response status code when a request gets blocked. You can configure this in the nginx.conf file by setting blocking_status_code field in the traceableai section. The default value is set to 403. The following is an example snippet, with the last line showing the blocking_status_code value set to 472.

traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }

Content capture

You can configure the type of content you wish to capture. Configure capture_content_types inside the traceableai section. Capturing of the following content types is supported:

• xml

• json

• grpc

• x-www-form-urlencoded

If you wish to capture xml json, specify the directive as capture_content_types xml json. If the directive is not specified, Traceable by default captures json, grpc, and x-www-form-urlencoded content as these are the most common content types.

traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        # capture content type
        capture_content_types xml json
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }

Step 4 - Reload NGINX

Enter the following command to reload NGINX configuration:

sudo nginx -s reload

Verify whether the installation was successful.

---

Ubuntu

Installing Traceable’s Tracing agent on NGINX community version running on Ubuntu 18.0.4 or 20.0.4 consists of the following steps:

1. Install Traceable’s Tracing agent

2. Edit nginx.conf file

3. Reload NGINX

Step 1 - Install NGINX tracing agent

Complete the following steps to install Traceable NGINX module:

1. Set up the apt repository. You might have already done this as part of setting up traceable-agent. For more information, see Setup the repository in Virtual machine topic.

2. Install the module. Replace "NN.N"with your NGINX version.

   ActionScript

   sudo apt-get install nginx-module-traceable-1.NN.N

Step 2 - Edit the configuration file

Edit your nginx.conf file, for example, /etc/nginx/nginx.conf

1. Add the load module directive after pid /run/nginx.pid

   load_module modules/ngx_http_traceableai_module.so;

2. Add the following to the nginx.conf file in the http block above the include /etc/nginx/conf.d/*.conf;line:

   ActionScript

   traceableai {
       service_name nginx;
       collector_host localhost;
       collector_port 9411;
       blocking on
       config_endpoint localhost:5441;
     }
     # enable monitoring for all requests.
     opentracing on;
     # propagate request context to upstream services
     opentracing_propagate_context;

If your location block has proxy_set_header set, add opentracing_propagate_context to the location block, else add opentracing_propagate_context to the http block as shown in step 2 above.

Optional - Add custom error code

You can add custom error code in 4xx series as response status code when a request gets blocked. You can configure this in the nginx.conf file by setting blocking_status_code field in the traceableai section. The default value is set to 403. Following is an example snippet with the last line showing the blocking_status_code value set to 472.

traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        #blocking_skip_internal_request off;
          blocking_status_code 472;
    }

Content capture

You can configure the type of content you wish to capture. Configure capture_content_types inside the traceableai section. Capturing of the following content types is supported:

• xml

• json

• grpc

• x-www-form-urlencoded

If you wish to capture xml json, specify the directive as capture_content_types xml json. If the directive is not specified, Traceable by default captures json, grpc, and x-www-form-urlencoded content as these are the most common content types.

traceableai {
        service_name "nginx";
        collector_host "host.docker.internal";
        collector_port 9411;
        blocking on;
        blocking_log_to_console on;
        config_endpoint host.docker.internal:5441;
        config_polling_period 30;
        #sampling off;
        api_discovery on;
        # capture content type
        capture_content_types xml json
        #blocking_skip_internal_request off;
        blocking_status_code 472;
    }

Step 3 - Reload NGINX

Enter the following command to reload NGINX configuration:

sudo nginx -s reload

---

Verification

You can complete the following steps to verify if the installation was successful:

1. Exercise the applications routing through NGINX

2. Visit the Traceable platform and confirm traces are showing up.

---

Upgrade

To upgrade the NGINX tracing agent:

1. Install the module as per the install section.

2. Update the config in nginx.conf if needed.

3. Restart nginx

---

Uninstall

Complete the following steps to uninstall NGINX tracing agent:

1. Depending on how the module was installed

   1. Remove the dynamic library files: ngx_http_traceableai.module.so and libtraceable.so.

      • For Amazon Linux 2 and CentOS

        ActionScript

        sudo yum remove nginx-module-traceable*

      • For Ubuntu

        ActionScript

        sudo apt-get remove nginx-module-traceable*

2. Remove the Traceable configuration lines from nginx.conf

3. Restart NGINX