Debugging OpenResty and Nginx Lua scripts with ZeroBrane Studio

12 MAY 2014

has already been used to debug various Lua engines -- game frameworks (like , , , ), , , , and more -- but there have been several Lua environments that I haven't tried it on. One of them is OpenResty/Nginx Lua scripts. is a web application server built around nginx, a very fast web server, that provides non-blocking IO with various backends (Redis, Memcached, MySQL, HTTP servers, and others) and supports Lua as its scripting language.

I first tried to use the non-blocking socket API that OpenResty provides, but couldn't get the debugging to work because socket calls that were supposed to be blocking were returning too early, which was breaking the interaction between the debugger in the application and the IDE. Based on advice from Yichun Zhang (agentzh), the maintainer of the OpenResty bundle, I then tried to use the same luasocket library that ZeroBrane Studio is using and got it all working. These are the steps you can follow to try it yourself:

ZeroBrane Studio configuration.

1. Get . These instructions are for Windows, but the debugging should work on Linux and OSX as well.

2. Start ZBS (zbstudio.exe or zbstudio.sh) and start the debugger Project | Start Debugger Server.

OpenResty configuration.

1. I'm using a very basic config (<NGINX>/conf/nginx.conf):

worker_processes  1;events {    worker_connections  1024;}http {    lua_package_path '
    
     /lualibs/?/?.lua;
     
      /lualibs/?.lua;;';    lua_package_cpath '
      
       /bin/clibs/?.dll;;';    server {        location /hellolua {           default_type 'text/plain';           content_by_lua_file 'lua/content.lua';        }    }}

Make sure you replace <ZBS> with the actual path to ZeroBrane Studio location. If you are running on OSX, replace ?.dll with ?.dylib and if you are running on Linux, replace bin/clibs/?.dll with either bin/linux/x86/clibs/?.so or bin/linux/x64/clibs/?.so depending on your platform.

2. Create the file we are going to debug (<NGINX>/lua/content.lua), which may look like this:

require('mobdebug').start('192.168.1.22')local name = ngx.var.arg_name or "Anonymous"ngx.say("Hello, ", name, "!")ngx.say("Done debugging.")require('mobdebug').done()

Note that start() call takes the IP of the computer running the IDE. It uses "localhost" by default, but since your nginx instance is running there, you will need to specify the IP address of the computer running the IDE (in my case it is 192.168.1.22).

3. Open this file (<NGINX>/lua/content.lua) file in the IDE and set the project directory to lua folder by going to Project | Project Directory | Set From Current File.

Script debugging.

Now start nginx and go to . If everything is right, you should see ZeroBrane Studio activated with the green arrow pointing to the second line (similar to what can be seen in the screenshot above). You can now set breakpoints, step through the code, look at the stack and so on.

You can also go to the remote console and run any ngx command there. For example, if you run ngx.say("Message from console") (as shown in the screenshot), you will see this text in the output after the script is done.

If you get "attempt to yield across C-call boundary" error in Nginx logs when you start debugging, try with a more recent ZeroBrane Studio (0.70+) as it includes several improvements that make debugging to work with recent versions of OpenResty.

OpenResty configuration for remote debugging.

The following steps are only needed if you configure OpenResty/Nginx for remote debugging when Nginx runs on one machine and ZeroBrane Studio runs on another one. When you run both on the same machine, Nginx is using modules included with ZeroBrane Studio as those are referenced by lua_package_path and lua_package_cpath directives.

1. Copy the debugger (mobdebug.lua) and socket files. Go to <ZBS>/lualibs/mobdebug/ and copy mobdebug.lua to<NGINX>/lua/mobdebug.lua; also copy <ZBS>/lualibs/socket.lua to <NGINX>/lua/. After all this is done, the content of lua folder is going to look like this:

./content.luamobdebug.luasocket.lua

2. Copy <ZBS>/bin/clibs/socket/core.dll to <NGINX>/socket/core.dll (core.dylib and core.so files are in the bin folder as well).

You should get a copy of my slick and follow me on twitter .

by Paul Kulchenko on Monday, May 12, 2014 at 9:22 PM

Filed in | Tagged , , , ,

Related Entries

10 Comments

Hi Paul, I've tried debugging in linux as your guide, but could not make it work. After I made a request to I got an error log in nginx's error.log, "[error] 23503#0: *22 lua entry thread aborted: runtime error: attempt to yield across C-call boundary" and nginx ended the request with a "500 Internal Server Error" response. It seemed that the luasocket which mobdebug is using produced the error. I was using openresty-1.5.8(with the bunlded LuaJIT-2.1-20140109) and zbstudio-0.60 in SuSE Linux, I also tried in Ubuntu 12.10 using openresty-1.5.12 and zbstudio-0.60 and got the same error. Did I miss somthing? Any suggestion? Any help would be greatly appreciated!

LiuJun | | Reply

Hi LiuJun, I initially got the same error -- "attempt to yield across C-call boundary" -- and this is why I switched to using "blocking" luasocket, as this is needed for the debugger. Is it possible that in your case you use a nonblocking luasocket that comes with OpenResty?

Try removing references to "luapackagecpath" and replacing the content of content.lua with something like: "print(1) require 'socket' print(2)". This should fail if luasocket is indeed unavailable. If it does correctly reference the version from ZeroBrane Studio, I don't see why it would fail, but I haven't tested it on Linux. I'll try to set it up on my VM to see if I can reproduce this issue.