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

NGINX community support

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;
    opa_server http://localhost:8181/;
    config_endpoint localhost:5441;
    opa_log_dir /tmp;
  }
  # enable monitoring for all requests.
  opentracing on;
  # propagate request context to upstream services
  opentracing_propagate_context;

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;
        #opa on;
        #opa_log_to_console off;
        opa_server http://host.docker.internal:8181/;
        opa_log_dir /var/log/traceable/;
        #opa_debug_log 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;
        #opa on;
        #opa_log_to_console off;
        opa_server http://host.docker.internal:8181/;
        opa_log_dir /var/log/traceable/;
        #opa_debug_log 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;
    opa_server http://localhost:8181/;
    config_endpoint localhost:5441;
    opa_log_dir /tmp;
  }
  # enable monitoring for all requests.
  opentracing on;
  # propagate request context to upstream services
  opentracing_propagate_context;

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;
        #opa on;
        #opa_log_to_console off;
        opa_server http://host.docker.internal:8181/;
        opa_log_dir /var/log/traceable/;
        #opa_debug_log 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;
        #opa on;
        #opa_log_to_console off;
        opa_server http://host.docker.internal:8181/;
        opa_log_dir /var/log/traceable/;
        #opa_debug_log 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;
       opa_server http://localhost:8181/;
       config_endpoint localhost:5441;
       opa_log_dir /tmp;
     }
     # enable monitoring for all requests.
     opentracing on;
     # propagate request context to upstream services
     opentracing_propagate_context;

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;
        #opa on;
        #opa_log_to_console off;
        opa_server http://host.docker.internal:8181/;
        opa_log_dir /var/log/traceable/;
        #opa_debug_log 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;
        #opa on;
        #opa_log_to_console off;
        opa_server http://host.docker.internal:8181/;
        opa_log_dir /var/log/traceable/;
        #opa_debug_log 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