- 27 Jan 2023
- 2 Minutes to read
- Print
- PDF
OpenResty
- Updated on 27 Jan 2023
- 2 Minutes to read
- Print
- PDF
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:
- Download Lua plugin file and dependencies.
- Configure the service name.
- 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.