OpenResty

OpenResty is a web platform that is built on top of the NGINX web server and LuaJIT. It includes a web server, a Lua-based programming language, and a set of Lua libraries for common web-related tasks. OpenResty allows developers to build high-performance web applications and services by leveraging the power of NGINX and Lua, and it is widely used in the development of web-based applications, APIs, and microservices. Traceable provides a Lua plugin file to capture user request passing through your OpenResty server. The following diagram shows the traffic flow through your OpenResty server. The Lua plugin captures the data and sends it to the Traceable Platform agent. The Platform agent in turn sends the data to the Traceable Platform.

Before you begin

Make a note of the following before proceeding with the deployment:

• Make sure that OpenResty is installed. For more information on OpenResty installation, see OpenResty® Linux Packages or Installation.
• Make sure that Traceable Platform agent is installed on the same host as OpenResty.
• Traceable supports OpenResty 1.19.9.1 and later.

Support

The following are protocols are supported:

• HTTP
• GraphQL
• GRPC
• GRPC-web

Traceable plugin for OpenResty supports request blocking.

Setup

Setting up Traceable's Lua plugin consists of the following steps:

1. Download Lua plugin file and dependencies.
2. Configure the service name. 
3. Add initialization code to your nginx.conf file.

Step 1 – Download the Lua plugin file

Navigate to Traceable's download site to download Traceable's OpenResty Lua plugin. Click on Install > openresty > plugin > latest to download the plugin. Save the downloaded file at /etc/nginx/traceable-plugin.lua.

Step 2 – Set the service name

Open the Lua plugin file to set the service name. The default service name is nginx and is set in localEndpoint as shown below from the snippet of the traceable-plugin.lua file.

local localEndpoint = {
  serviceName = "nginx"
}

Install resty-http lua module

Enter the following command to install resty-http Lua module:

opm install ledgetech/lua-resty-http=0.16.1

Step 3 - Initialize the plugin

Edit your current nginx.conf file to use Traceable's Lua plugin.

worker_processes  1;
error_log logs/error.log;
events {
    worker_connections 1024;
}
http {
    lua_package_path "/etc/nginx/lua/?.lua;;";
   
    init_by_lua_block {
      traceable = require "traceable-plugin"
    }
    rewrite_by_lua_block {
      traceable.rewrite()
    }
    log_by_lua_block {
      traceable.log()
    }
    body_filter_by_lua_block {
      traceable.body_filter()
    }

    server {
        <your_server_configuration>
    }
}

Restart the OpenResty server

Enter the following command to restart the OpenResty server

sudo systemctl restart openresty

Blocking configuration

To turn blocking capabilities on or off, edit Traceable agent's config.yml. You will need to edit the ext_cap.blocking_config.enabled property to either true or false. The file is typically located at /etc/traceable/agent/config.yaml for Traceable Platform agent installed on a Linux machine.

ext_cap:
  blocking_config:
    enabled: false

To disable blocking on Traceable Platform agent installed in a Kubernetes environment, use the following values file while installing or modifying the Traceable Platform agent:

blockingEnabled: false
injector:
  blockingConfig:
    enabled: false

Verification

To verify the deployment, send a request and check it in Traceable Platform. 

In case if you do not see any requests in Traceable Platform, check the NGINX error logs. Traceable Lua plugin errors are reported in NGINX error logs.

Upgrade

To upgrade to Traceable's latest Lua plugin, repeat the Setup steps with the new plugin file. 

Uninstall

Uninstall Traceable's Lua plugin by removing the configuration from nginx.conf file.