- 08 Apr 2022
- 2 Minutes to read
-
Print
OpenResty
- Updated on 08 Apr 2022
- 2 Minutes to read
-
Print
OpenResty is a web platform built on NGINX core having LuaJIT. 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 Traceable Platform agent. The Platform agent in turn sends the data to 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 > 1.17.1 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 Platforma 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.