When you run a Lua script and the script fails due to an error, CFS writes the error to the import log stream, and to the ImportErrorDescription
field of any documents that are affected.
To debug your Lua scripts, you can use the LuaDebug
action. You can use this action to pause and resume scripts, and set and remove breakpoints. When a script is paused you can view the values of variables, view a stack trace, and step over single lines.
CFS can have more than one import thread, and might run multiple Lua scripts concurrently. This means that you can have multiple Lua Debugging sessions. You might want to pause or continue running scripts on one thread but not others. Some of the commands available through the LuaDebug
action allow or require you to specify a session
action parameter. If the session
parameter is optional and you do not specify a session, the command applies to all sessions. To view open sessions and obtain the values you can set for the session
action parameter, use the command /action=LuaDebug&command=get-status
.
The following procedure demonstrates how to set a breakpoint in a script, view the values of Lua variables when the script is paused, and step over single lines. The actions in this procedure assume that your CFS is running on the local machine and is listening for actions on port 7000. For more information about the LuaDebug
action, refer to the Connector Framework Server Reference.
To debug a Lua script
In the CFS configuration file, configure the script to run. This example uses the AddLanguageDetectionFields
script that is included with CFS. For example:
[ImportTasks] Post0=Lua:scripts/AddLanguageDetectionFields.lua
To pause the script before a specific line is executed, set a breakpoint on that line. Line 33 of the AddLanguageDetectionFields
script sends an action to IDOL Server and stores the response in a variable named response
. To stop the script before this happens, use the following action:
http://localhost:7000/action=luadebug &command=set-breakpoint
&file=scripts/AddLanguageDetectionFields.lua &line=33
(Optional) Confirm the breakpoint has been set using the get-breakpoints
command:
http://localhost:7000/action=luadebug&command=get-breakpoints
CFS returns the response.
<autnresponse xmlns:autn="http://schemas.autonomy.com/aci/"> <action>LUADEBUG</action> <response>SUCCESS</response> <responsedata> <data> <command>get-breakpoints</command> <breakpoints> <breakpoint source="C:\Autonomy\ConnectorFramework\scripts\AddLanguageDetectionFields.lua" line="33"/> </breakpoints> </data> </responsedata> </autnresponse>
Send CFS an IngestTest
action so that CFS ingests a document and runs the script:
http://localhost:7000/action=IngestTest&adds=...
Use an IngestTest
action, rather than an Ingest
action, because the IngestTest
action does not index any information into IDOL Server. For more information about the IngestTest
action, see Ingest Data for Testing.
CFS runs the script. The IngestTest
action does not finish (because the script is paused at the breakpoint) and therefore does not return a response.
Retrieve a token for the debugging session by sending CFS the LuaDebug
command get-status
:
http://localhost:7000/action=LuaDebug&command=get-status
CFS returns the response. You can see that there is a single debugging session and the Lua script has stopped at the breakpoint.
<autnresponse xmlns:autn="http://schemas.autonomy.com/aci/"> <action>LUADEBUG</action> <response>SUCCESS</response> <responsedata> <data> <command>get-status</command> <session id="e4f7c45f561930cd17a5aed0fe1481d8"> <status>AtBreak</status> </session> </data> </responsedata> </autnresponse>
To retrieve the values of the Lua variables at the breakpoint, run the LuaDebug
command get-locals
. Use the session token that you retrieved with the get-status
command:
http://localhost:7000/action=LuaDebug &command=get-locals &session=e4f7c45f561930cd17a5aed0fe1481d8
CFS returns the response.
<autnresponse xmlns:autn="http://schemas.autonomy.com/aci/"> <action>LUADEBUG</action> <response>SUCCESS</response> <responsedata> <data> <command>get-locals</command> <session id="e4f7c45f561930cd17a5aed0fe1481d8"> <locals> ... <local name="idolHost" type="string">localhost</local> <local name="idolACIPort" type="number">9000</local> <local name="timeout" type="number">30000</local> ... ... <local type="string" name="detectionString">This is a document that contains text in English. Automatic Language Detection will detect the language and add the information to the document ...</local> </locals> </session> </data> </responsedata> </autnresponse>
Use the step
command to run line 33. CFS does not run subsequent lines (the script will remain paused). Use the session token you retrieved with the get-status
command:
http://localhost:7000/action=LuaDebug
&command=step &session=e4f7c45f561930cd17a5aed0fe1481d8
CFS returns the response.
<autnresponse xmlns:autn="http://schemas.autonomy.com/aci/"> <action>LUADEBUG</action> <response>SUCCESS</response> <responsedata> <data> <command>step</command> <session id="e4f7c45f561930cd17a5aed0fe1481d8"/> </data> </responsedata> </autnresponse>
To see what effect the step had on the variables, run the get-locals
command again. You should see a new variable named response
that contains the response from the DetectLanguage
action.
http://localhost:7000/action=LuaDebug &command=get-locals &session=e4f7c45f561930cd17a5aed0fe1481d8
After examining the variables, you might want to remove the breakpoint. To remove the breakpoint, send CFS the following action:
http://localhost:7000/action=LuaDebug &command=remove-breakpoint
&file=scripts/AddLanguageDetectionFields.lua &line=33
CFS returns the response. You can also use /action=LuaDebug&command=get-breakpoints
to confirm that the breakpoint has been removed.
To continue running the Lua script, use the continue
command:
http://localhost:7000/action=LuaDebug
&command=continue &session=e4f7c45f561930cd17a5aed0fe1481d8
CFS continues to run the script. The IngestTest
action finishes and returns a response.
|