Developing Productions
Testing and Debugging
|
|
This topic explains the facilities available for testing and debugging productions. The information is also useful for troubleshooting and tuning production software that is already in use at the enterprise. Topics include:
Correcting Production Problem States
Recovering a Suspended Production
A production acquires the Suspended status when, at the end of the shutdown sequence, some queues still contain synchronous messages. If this is the case, you can start the Suspended production again to permit these messages to be processed.
However, if the problem that originally caused the Suspended status is not resolved, starting a Suspended production can just as easily add more synchronous messages to a queue, without discharging the previous messages and return the production to a Suspended status.
You may stop a Suspended production. InterSystems advises you do so only during initial development and not on a deployed, live installation.
If you find this is the case, you may sometimes need to take more drastic action to fully clean up after a production that goes into the Suspended state. InterSystems IRIS™ provides the
CleanProduction() method for this case.
Caution:
Never use this procedure on a live, deployed production. The
CleanProduction() method removes all messages from queues and removes all current information about the production. Use this procedure only on a production that is still under development. If a live, deployed production goes into a Suspended state, contact the
InterSystems Worldwide Response Center (WRC) for assistance.
If you have exhausted all means to correct the problem and, therefore, are sure that a Suspended production
must stop, discarding even synchronous messages that have not yet been delivered, then use the following procedure:
-
Start the Suspended production from the
[Interoperability] > [Production Configuration] page by clicking
Start in the ribbon bar; the production status changes to Running.
-
Now click
Stop to verify the problem still exists. If the production stops successfully, there is no need to clean the production; if the production status returns to Suspended, continue with the next step.
-
Kill the production from a Terminal session as follows:
-
Change to the appropriate namespace:
Where
EnsSpace is the name of the production-enabled namespace where the Suspended production runs.
-
Enter the following command:
Do ##class(Ens.Director).CleanProduction()
-
Verify the production status from the
[Interoperability] > [Production Configuration] page; the
Status of the production should now be Stopped.
Recovering a Troubled Production
A production acquires a status of Troubled if InterSystems IRIS is stopped but the production did not shut down properly. This can happen if you restarted InterSystems IRIS or rebooted the machine without first stopping the production.
In this case the
Recover command appears on the
[Interoperability] > [Production Configuration] page. Click
Recover to shut down and clean up the troubled instance of the production so that you can run a new instance when you are ready.
Testing from the Management Portal
You can use the Management Portal to perform several tasks as you develop, test, and debug your productions:
-
Ability to view and modify system configuration.
-
Ability to start and stop a production.
-
Ability to view queues and their contents; messages and their details; adapters and actors and their status; business processes and their status; code and graphical representations of configured items.
-
Ability to view, sort, and selectively purge Event Log entries.
-
Ability to suspend (and later resend) messages whose connectivity is temporarily blocked.
-
Ability to filter and search the message warehouse for specific messages, by category or message content, using a graphical user interface or by entering SQL SELECT commands.
-
Ability to visually trace message activity using a graphical user interface.
-
Ability to create and view statistical reports.
Portal features that are most useful for developers are the Monitor Service, which constantly collects runtime data, the Testing Service, which you can use to issue simulated requests into a production that you are developing, and the Event Log, which logs the status messages issued by business hosts. Use these features together to generate test data and study the results.
The Management Portal has a Test menu where you can test both business hosts and data transformations. It contains the following items:
-
Business Hosts The
[Interoperability] > [Testing Service] page allows you to test business processes and business operations.
-
Data Transformations This option brings you to another page, where you can select a data transformation and click Test. For details, see the Testing Data Transformations section.
Using the Testing Service
The
[Interoperability] > [Testing Service] page allows you to test a business process or business operation of a running production in the active namespace. You can navigate to the Testing Service from the following locations in the Management Portal:
-
-
From the configuration diagram on the
[Interoperability] > [Production Configuration] page, click a business process or business operation in the left pane and click
Test on the
Actions tab.
Now, to use the Testing Service:
-
-
Make sure that testing is enabled for this production. Access the
[Interoperability] > [Productions] as usual. With the production selected, select the
Testing Enabled check box, click
Apply, and then click
OK.
-
In the Management Portal, click
Interoperability, click
and then
to display the
[Interoperability] > [Testing Service] page.
-
-
Select the testing target from the drop-down list.
-
Select the type of message to send. The page displays the following fields:
-
-
Target The business process or business operation that you selected in the previous Testing Service page (view-only).
-
Request Type Select from a list of request messages. Only the request types that are valid for the
Target are listed, including subclasses of supported types.
-
Enter values for the properties of the message that you selected.
If the request message has no properties, none are displayed.
If you are testing a virtual document message, there is a free-form box where you can paste test message content. Below this box you can enter object properties for the message.
-
Click
Invoke to submit the request with the values you entered and view the results.
If time elapses while the Testing Service attempts the request, a
Waiting page displays the following view-only information:
-
Target The session ID associated with the request.
-
-
Session Id The session ID associated with the request.
-
-
Finally, the
Results page displays any output values from the response generated by your request, including any errors with the full error message text.
You can perform one of the following commands when the test completes:
-
Click
Done to return to the home page.
-
Click
Trace to navigate to the Visual Trace page to visually follow the path of the message through the production.
Debugging Production Code
-
Using Studio, insert the
BREAK command where you want to start debugging.
-
Enable the
Foreground setting for the business host that uses the class you want to debug.
-
Start the production. The job that you marked in Step 2 runs in the foreground in the Terminal.
-
When that
BREAK command is reached, the Terminal enters debug mode and you can step through the code.
You can also debug your code in Studio:
-
With a business service, you still specify that it should be run in the foreground and use a BREAK to get the process ID.
-
With a business process, you can use Studio to set a breakpoint and then attach to the process to debug using Studio. In contrast, if you use BPL, Studio displays in .INT code.
-
With a business operation, you can use Studio to set a breakpoint and then attach to the operation process to debug.
The Event Log automatically includes partial information about system-level exceptions (including exceptions in your code). These Event Log entries end as follows by default:
-- logged as '-' number - @' quit arg1/arg2 }'
To get more complete information about such errors:
-
This causes InterSystems IRIS to record additional details for system-level exceptions.
-
Rerun the code that you think caused the exception (for example, resend messages).
-
Recheck the Event Log, which now contains entries that end as follows:
-- logged as '25 Sep 2012' number 15 @' quit arg1/arg2 }'
This information refers to an entry in the Application Error Log specifically it refers to error 15 in the Application Error Log for 25 September 2012.
-
Then to examine these exceptions, you can either: