Developing Ensemble Productions
Testing and Debugging
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   

This topic explains the facilities available for testing and debugging Ensemble 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
If a production is Suspended or Troubled, read this section.
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. Ensemble provides the CleanProduction() method for this case.
Never use this procedure on a live, deployed Ensemble 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 Ensemble 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:
  1. Start the Suspended production from the Production Configuration page by clicking Start in the ribbon bar; the production status changes to Running.
  2. 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.
  3. Kill the production from a Terminal session as follows:
    1. Change to the appropriate namespace:
        ZN "EnsSpace"
      Where EnsSpace is the name of the Ensemble namespace where the Suspended production runs.
    2. Enter the following command:
        Do ##class(Ens.Director).CleanProduction()
  4. Verify the production status from the Production Configuration page; the Status of the production should now be Stopped.
Only run the CleanProduction() method on a production in a Suspended state.
Recovering a Troubled Production
A production acquires a status of Troubled if Ensemble is stopped but the production did not shut down properly. This can happen if you restarted Ensemble or rebooted the machine without first stopping the production.
In this case the Recover command appears on the 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.
Or you may need to use the command line to recover the production. See Using Ens.Director to Start and Stop a Production,” earlier in this book.
Testing from the Management Portal
You can use the Management Portal to perform several tasks as you develop, test, and debug your productions:
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.
For information on using the portal, see Managing Ensemble.
The Management Portal has a Test menu where you can test both business hosts and data transformations. It contains the following items:
Using the Testing Service
The Testing Service page allows you to test a business process or business operation of a running Ensemble production in the active namespace. You can navigate to the Testing Service from the following locations in the Management Portal:
Now, to use the Testing Service:
  1. Make sure the appropriate production is running. See Managing Ensemble.
  2. Make sure that testing is enabled for this production. From the Production Configuration page:
    1. Select the Production Settings link.
    2. On the Settings tab, open the Development and Debugging property list and check the Testing Enabled check box.
    3. Select Apply.
  3. In the Management Portal, click Ensemble > Test > Business Hosts to display the Testing Service page.
    This page provides options that let you select either a Business Process or Business Operation as the target of your testing.
  4. Select either Business Process or Business Operation as appropriate.
  5. Select the testing target from the drop-down list.
  6. Select the type of message to send. The page displays the following fields:
  7. 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 (HL7, X12), there is a free-form box where you can paste test message content. Below this box you can enter object properties for the message.
  8. 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:
    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:
You can also use the classes and methods in the EnsLib.Testing package. See the EnsLib.Testing.Service entry in the Class Reference for details.
Debugging Production Code
The first step in debugging is to enable tracing as described in Monitoring Ensemble Productions. If this does not reveal the problem, you can step into the code using the debugger, as follows:
  1. Using Studio, insert the BREAK command where you want to start debugging.
  2. Enable the Foreground setting for the business host that uses the class you want to debug.
  3. Start the production. The job that you marked in Step 2 runs in the foreground in the Terminal.
  4. When that BREAK command is reached, the Terminal enters debug mode and you can step through the code.
For details, see Command-Line Routine Debugging in Using Caché ObjectScript.
You can also debug your code in Studio:
For details, see Using the Studio Debugger in Using Studio.
Enabling %ETN Logging
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:
  1. Set the ^Ens.Debug("LogETN") global node to any value.
    This causes Ensemble to record additional details for system-level exceptions.
  2. Rerun the code that you think caused the exception (for example, resend messages).
  3. 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.
  4. Then to examine these exceptions, you can either: