Troubleshooting an SDA Plug-in


Sometimes, whether it's with your own custom SDA plugin or a community/Serena provided plugin, we simply don't get the results we are expecting and need to do some troubleshooting.   Today we're going to talk about the easiest way we do it.

 First, a reminder or short overview as to how plugins work.  Plugins are loaded into the SDA server and are tagged with an identifier.  When it runs that plugin step on an agent, it will push the plugin down to the agent if needed, or just use it if it's already there.  If you upgrade or modify a plugin and load it into the SDA server, the identifier is different and SDA will know whether the agent needs it or not.  Long story short, there are unique identifiers added to the plugin when pushed to the agents.

Step one in troubleshooting is to locate our plugin files on an agent that we want to use for troubleshooting.  The goal here is to modify the agent's plugin files in-place, which avoids us having to repeatedly upload the plugin to the server and potentially increment several versions simply to troubleshoot.  Plugins are stored on the agent in the following directory: AGENT_INSTALL_DIR/corE/var/plugins.

For this example, we'll use a very basic process that leverages the shell command to say "hello", and we'll add some additional output/debugging steps to aid in troubleshooting.  To get started, we can find the plugin files located in our agent's directory, as shown in figure 1.  Note the long identifier after the plugin name.  If I had multiple versions of the shell plugin, I would see multiple directories, each with their own unique identifier.  In this case my agent is installed on a windows machine under "program files"

Figure 1.

Opening this folder, I can see the plugin files extracted as shown in figure 2.  What we are looking for is the groovy file (or other command file if using a different file type) that is being called by our step.  In many cases this will be intuitive as it is in this case.  Obviously, we want the shell.groovy file.  If we were unsure, we could look in the plugin.xml to find our step, and then learn the corresponding command file.

Figure 2.

For this example, we have a very basic process that has a single "shell" step, with a command of "echo Hello".  If we run our process and view the output, we'll see the below:

To demonstrate troubleshooting techniques, we will modify the shell.groovy file on the agent to output additional debugging/troubleshooting messages.  Opening shell.groovy in an editor, we can scroll down to line 220 and see the following block of code:


For the purpose of this example, we're simply going to add a line after line 223 that reads:

println("this is debugging output")

And then we save the file.  That's all we need to do.  There is no zipping anything up that is needed, or uploading a new version of the plugin to SDA.  All we need to do is to edit the groovy file within the agent directory, save it, and then run the process again.  SDA will invoke our recently modified file, and we should see the results shown below.  Note our new debugging output highlighted on line 4.

This was a basic example, but illustrated the point that updating agent files in-place as a troubleshooting technique can save you a significant amount of time.  Often, you will find that you were simply passing a parameter incorrectly and no actual updates are needed.  Adding multiple println statements can help you determine the point of failure if it's not clear, as well as to understand the value of parameters being used.

If you do find that a plug-in modification is required, all you need to do is to zip up the agent's files, upload that zip file into SDA, and SDA will automatically distribute your updates to the other agents.  Remember, as long as you are only modifying command files (and not the plugin.xml file) then no version increment is needed.  



How To-Best Practice
Comment List
Related Discussions