feat: add EmmyLuaDebugger hook

[hanshuebner]

Summary

The change provides a hook in the init_worker phase to start the EmmyLua debugger. The debugger is enabled by setting the KONG_EMMY_DEBUGGER to the absolute pathname of the EmmyLuaDebugger shared library (e.g. /usr/local/bin/emmy_core.dylib). The host and port that the debugger interface listens on can be defined by setting the KONG_EMMY_DEBUGGER_HOST and KONG_EMMY_DEBUGGER_PORT environment variables, respectively.

If the environment variable KONG_EMMY_DEBUGGER_WAIT is set, the debugger hook waits for the IDE to connect at the beginning of the worker startup process to allow debugging of startup issues.

Kong should be started withKONG_NGINX_WORKER_PROCESSES set to 1 to enable only one worker process. Debugging multiple worker processes is not supported.

This feature is based on work by @mehuled, published in
https://dev.to/mehuled/breakpoint-debugging-with-kong-plugin-development-75a

Checklist

• The Pull Request has tests
• A changelog file has been created under changelog/unreleased/kong or skip-changelog label added on PR if changelog is unnecessary. README.md
• There is a user-facing docs PR against https://github.com/Kong/docs.konghq.com - PUT DOCS PR HERE

KAG-4316

[gszr]

Very nice addition, @hanshuebner! Wondering if this shouldn't be loaded along with luacov -- see https://github.com/kong/kong/blob/38ddd0e203240cdb1d6c5352ea4b5dca9de0ce51/kong/templates/nginx_kong.lua#L43. Maybe introducing a "dev" mode would be appropriate?

[hanshuebner]

@gszr writes:

Maybe introducing a "dev" mode would be appropriate?

I'm not quite sure - luacov seems to be useful when running (all) tests, while the debugger really only helps in interactive mode. Also, if I understand you well, you're suggesting that a "dev" mode should exist which enables certain things. We'd have to ship EmmyLuaDebugger in that case, otherwise one would have to enable "dev" mode and specify the location of the debugger shared library. If it'd be the other way round and setting KONG_EMMY_DEBUGGER would enable "dev" mode, I'd find that to be kind of awkward as well.

I think debuggers are most useful if they require little or no setup. I think with the current setup, it is possible to always set the KONG_EMMY_DEBUGGER and KONG_NGINX_WORKER_PROCESSES variable (i.e. in .profile) and thus basically always have the debugger available. This could certainly work with a "dev" mode as well, but I'm not certain as to what that should exactly encompass.

[bungle]

Just checking.

[jschmid1]

successfully tested on Ubuntu 22.04.

Ubuntu 20.04's GLIBC version is too low however. We may want to include glibc version requirements in the docs at some point.

[hanshuebner]

Ubuntu 20.04's GLIBC version is too low however. We may want to include glibc version requirements in the docs at some point.

I've added a paragraph to DEVELOPER.md.

Comment resolved - cpath is now only changed while loading debugger

[team-gateway-bot]

Successfully created cherry-pick PR for master:

• https://github.com/kong/kong-ee/pull/8982