Debug a Lua Script

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.

Sessions

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.

Example

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

  1. 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
  2. Start CFS.
  3. 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
  4. (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>
  5. Send CFS an IngestTest action so that CFS ingests a document and runs the script:

    http://localhost:7000/action=IngestTest&adds=...

    TIP: 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.

  6. 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>
  7. 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>
  8. 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>
  9. 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
  10. 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.

  11. 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.