How to customize a plugin response to make it more meaningful

How can I customize the output/response of plugins e.g. bot detection to illustrate the reasons behind certain responses e.g. “Forbidden”

To provide more informative responses from, for example, the bot detection plugin, you can use the exit-transformer plugin to customize the output. This approach allows you to append specific messages to the response body, based on the HTTP status codes returned by Kong, indicating the reason for the response, such as detection as a bot.

Here are the steps to set up the exit-transformer plugin for verbose output:

1. Create a Lua script named transform.lua with the following content:

   return function(status, body, headers)
       if status == 401 then
           body.message = "Unauthorized"
       end
       if status == 403 then
           body.message = "Forbidden, detected as bot"
       end
       if status == 429 then
           body.message = "Retry again later"
       end
       return status, body, headers
   end

   Copied!

2. Apply the exit-transformer plugin to a route or service. Use the following command as an example to set it up on a route:

   curl -X POST -H "Kong-Admin-Token:password" http://api.kong.lan/routes/local-httpbin/plugins \
       --form 'name="exit-transformer"' \
       --form 'config.functions=@"transform.lua"'

   Copied!

3. Test the setup by making a request that would trigger the plugin. For example, using a user-agent that is detected as a bot:

   curl http://localhost:8000/httpbin -A "Googlebot"

   Copied!

   The response should now include the customized message:

   {"request_id":"61b4f06cc3719e4410464120c3a83054","message":"Forbidden, detected as bot"}

   Copied!

Additionally, when logging plugins like http-log or file-log are enabled, the user-agent and other relevant information are logged in the Data Plane logs, which can be useful for debugging purposes.

Additional Tips:

• For a more comprehensive view of the plugins involved in processing a request, consider using the OpenTelemetry plugin, which provides visibility into the spans captured and can help developers understand the flow of requests through the plugins.
• Remember to remove or adjust the verbose output settings when moving from the development stage to production to avoid exposing unnecessary information.