Capturing Traces in Verastream Host Integrator

  • Document ID:7021562
  • Creation Date:17-Jun-2010
  • Modified Date:06-Aug-2021
    • Micro Focus Products:
      Verastream Host Integrator (VHI)

Environment

Verastream Host Integrator

Situation

If you are working with Technical Support on a Verastream Host Integrator (VHI) issue, you may be asked to provide a trace file. Some issues with the session server, host communication, or event handlers may require traces. This technical note describes how to capture and send a trace.

Do I need a trace?

Most Host Integrator issues are resolved by using the following troubleshooting tools:

Resolution

Topics:
Design Tool Debug Trace
Session Server Trace, Version 7.0 or Higher
Session Server Trace, Version 6.6 or Earlier
Log4j Trace
Event Handler Trace
Design Tool Datastream Trace (.hst)
Connector WCP Trace
Host Emulator Trace
Network Trace
Sending Your Trace(s) to Technical Support

Design Tool Debug Trace

If an issue is reproducible while connected to the host in Design Tool, capture a Design Tool debug trace.

To configure the trace:

  1. Open the Design Tool.
  2. Select Debug > Debug Trace > Configure Debug Trace.
  3. Select the trace nodes suggested by Technical Support, or select all options.

Note: You will need to manually expand and select all sub-options. Selecting the main option check box does not automatically select the sub-options.

  1. Click Save As and save the configuration file with a name you will remember. For example, you might name the file traceconfig1.cfgtrc.

To start the trace:

If the problem exists close to when you log into the host application, make sure that you are disconnected from the host within the Design Tool before starting the trace; otherwise, verify that Verastream is open to a working entity when you start the trace (before getting into the entity where the problem actually occurs). This way the trace displays a clear view of what is happening when the problem entity is displayed.

    1. Click Debug > Debug Trace > Start Debug Trace.
    2. Specify a filename and make note of the directory where the file will be saved. For example, C:\Program Files\VHI\etc\tracing\debug.trace.
    3. Duplicate the problem in Design Tool.

To stop the trace:

To stop the trace, click Debug > Debug Trace > Stop Debug Trace.

Note: The trace file created is binary.

Session Server Trace, Version 7.0 or Higher

Follow the steps below to capture a session server trace in version 7.0 or higher. This troubleshooting may be necessary if the problem cannot be captured by debug tracing in the Debug Tool.

To configure the trace:

  1. Run Administrative Console from the installed shortcut.
  2. Connect to the management server and log in with Administrator credentials (such as the “admin” user name and administrative password set during installation).
  3. If Session Server Explorer is not currently displayed, click Perspective > Host Integrator > Session Servers.
  4. Under Servers, right click your server name and click Properties.
  5. In the server properties dialog, in the left tree, click the Tracing category.
  6. In the Trace File Name field, enter a path and file name such as C:\Program Files\Attachmate\Verastream\HostIntegrator\etc\tracing\trace1.trace (for session server running on Windows) or /opt/attachmate/verastream/hostintegrator/etc/tracing/trace1.trace (for session server running on Linux/UNIX).

Note: This path and file name must be less than 1024 characters. The directory must already exist and be writable by the system account that runs the Session Server service.

  1. Enable the trace nodes suggested by Technical Support. Or, to use a trace configuration file created in Design Tool or provided by Attachmate, right click anywhere in the trace node tree and select Load Trace Configuration File.
  2. Click OK to save changes and close the server properties dialog.

To start the trace:

  1. In Session Server Explorer, right click your server and click Start Tracing.

Note: Depending on the configured trace options, the increased disk write activity of tracing may impact performance. In a production environment with high activity, stop the trace as soon as possible.

To stop the trace:

  1. In Session Server Explorer, right click your server and click Stop Tracing.

Note: The trace file created is binary. This file can be analyzed by Attachmate only. Send only the .trace file to Attachmate; it is not necessary to send the .cfgtrc file.

Session Server Trace, Version 6.6 or Earlier

Follow the steps below to capture a session server trace in version 6.6 or earlier. This troubleshooting may be necessary if the problem cannot be captured by debug tracing in the Debug Tool.

Before creating a server trace:

  1. Follow the steps presented in the Design Tool Debug Trace section above to obtain a Design Tool configuration trace file.
  2. Copy or FTP (binary) the .cfgtrc file to the Verastream Host Integrator server machine, to the <VHI>/etc/tracing directory.

To configure the trace:

  1. Start the Verastream Administrative WebStation console:

Local Windows installation: Use the Administrative WebStation shortcut installed in the Start programs folder.

Local UNIX installation: Use a web browser to open <vhi>/bin/VHI_Administrative_WebStation_Login.html where <vhi> represents your Verastream Host Integrator installation directory.

Remote system: In a web browser, open http://<hostname>:9642/apptrieve where <hostname> represents the system running the Verastream Host Integrator Administrative WebStation service.

  1. If security is enabled, enter credentials for a user in the Administrator security profile. Click Log In.
  2. Click Config.mode (on the top navigation bar) to go into configuration mode.
  3. In the navigation tree, click Servers > [your Verastream server] > Server Configuration > Tracing > Load Trace Configuration.
  4. Specify the exact location of the configuration trace file. For example, \Program Files\VHI\etc\tracing\traceconfig1.cfgtrc in Windows, or /usr/local/vhi/etc/tracing/traceconfig1.cfgtrc in UNIX/Linux.
  5. Click Save.

To start the trace:

  1. Navigate back to Server Configuration > Tracing.
  2. Specify a trace filename. For example, C:\Program Files\VHI\etc\tracing\server.trace in Windows, or /usr/vhi/etc/tracing/server.trace in UNIX/Linux. Note: This path and file name must be less than 1024 characters, and should be on a local drive accessible by the system account that runs the VHI services.
  3. Select Trace New Sessions. Also, if you are troubleshooting a problem that happens when the session server is started (such as pooled sessions connecting), enable Trace Server Startup.
  4. Click Save.
  5. Above the left navigation tree, click Start Trace. However, if you are tracing at server startup, restart the session server service instead (see KB 7021352).
  6. Run the client application to duplicate the problem.

Note: Depending on the configured trace options, the increased disk write activity of tracing may impact performance. In a production environment with high activity, stop the trace as soon as possible.

To stop the trace:

  1. Select Tracing.
  2. Click Stop Trace (above the navigation tree).
  3. From the top navigation bar, select the 'View Mode' button to exit configuration mode.

Note: The trace file created is binary. This file can be analyzed by Attachmate only. Send only the .trace file to Attachmate; it is not necessary to send the .cfgtrc file.

Log4j Trace

Beginning in version 7.0, a number of components use the log4j utility for logging and tracing. For more information, see KB 7021322.

Event Handler Trace

If you have an event handler script server issue that cannot be resolved with stream output or an external debugger, Technical Support may request that you enable tracing for in-depth troubleshooting.

  1. Configure the output.

.NET: Enable the stream output as described at http://docs2.attachmate.com/verastream/vhi/7.1/en/topic/com.attachmate.vhi.help/html/reference/event_handler_debugging.xhtml. Also, in %VHI_ROOT%\lib\dotnet\clrscriptserver.exe.config, set TraceToStandardOut to true.

Java, version 7.0 or higher: Enable log4 tracing for either the Design Tool or Session Server script server, as appropriate, as described in KB 7021322.

Java, version 6.6 or earlier: In the %VHI_ROOT%\etc directory, create a script.properties file by copying the installed script.properties.sample file. To capture System.out and System.err streams (in handlers.out file), uncomment the vhi.script.output.file=true line. To generate stack dumps for unhandled exceptions (in user classes, not ApptrieveException or EventTimeoutException) in the traps.out file, uncomment the vhi.script.output.traps=true line.

  1. Enable the appropriate Event Handling trace nodes. Refer to the appropriate section above (Design Tool Debug Trace or Session Server Trace, Version 7.0 or Higher).

Note: If you need to trace a problem with the startup of the .NET script server, edit the XML file %VHI_ROOT%\lib\dotnet\clrscriptserver.exe.config to set TraceStartup to true. This will enable all the Event Handling trace nodes.

If you need to trace a problem with the startup of the Java script engine in version 6.6 or earlier, edit the script.properties file to add the line vhi.script.trace.startup=true.

  1. Configure a trace file name and start the trace. Refer to the appropriate section above (Design Tool Debug Trace or Session Server Trace, Version 7.0 or Higher).

Note: Although tracing for Event Handling trace nodes (script servers) is not written to the binary trace file, you must still set a trace file name.

  1. Reproduce the problem.
  2. View the output. The default locations are as follows.

.NET:%VHI_ROOT%/etc/output/handlers.out

Java, Design Tool, version 7.x:%VHI_ROOT%\destool\logs\server.log

Java, Session Server, version 7.x:%VHI_ROOT%/sesssrvr/logs/server.log

Java, version 6.6 and earlier: For script engine startup issues, provide the %VHI_ROOT%/etc/tracing/startup.trace file to Technical Support

Design Tool Datastream Trace (.hst)

This feature is only available for IBM (3270 and 5250) emulations. For VT or HP emulations, use Design Tool Debug Trace instead.

With the Design Tool's datastream trace feature, you can record data transmissions to and from the host. Although this trace is intended primarily for diagnostic purposes, you can use the playback feature to redisplay the host's output to your screen. Playback does not redisplay the user's input.

If the problem exists close to when you log into the host application, make sure that you are disconnected from the host within the Design Tool before starting the trace; otherwise, verify that Verastream is open to a working entity when you start the trace (before getting into the entity where the problem actually occurs). This way the trace will display a clear view of what is happening when the problem entity is displayed.

To start the trace:

  1. Select the menu Connection > Datastream Trace > Start Trace.
  2. Specify a filename. For example: \Program Files\VHI\etc\tracing\datastream.hst.
  3. Click Trace.
  4. Duplicate the problem.

To stop the trace:

  1. Click Connection > Datastream Trace > Stop Trace.

Note: The .hst datastream trace file created is binary.

Connector WCP Trace

For information on collecting a trace of WCP communication on the client (connector), see KB 7021304.

Host Emulator Trace

In version 7.0 or higher, if you are using Host Emulator for demonstration, training, or testing purposes, you can capture the communication between session server and the emulated host. For more information, see http://docs2.attachmate.com/verastream/vhi/7.1/en/topic/com.attachmate.vhi.vmc.help.online/tasks/vhi_em_model_tracing.xhtml.

Network Trace

In some situations, a network sniffer trace capture may be necessary, particularly if other tracing or troubleshooting tools affect timing or mask the issue. Use a third-party network capture utility, such as Wireshark (formerly Ethereal) or network hardware. To obtain Wireshark, go to http://www.wireshark.org/download.html.

To monitor web services (HTTP) communications with the embedded SOAP stack, use the Apache TCPMon utility (http://ws.apache.org/commons/tcpmon/) or Fiddler (http://www.fiddlertool.com/) as an intermediary or proxy.

Above references to third-party vendors or products are informational only and should not be construed as certification, endorsement, or recommendation by Attachmate.

Sending a Trace to Support

If you are already working with Technical Support, see the instructions at https://support.microfocus.com/kb/doc.php?id=7024990 on how to upload any files gathered.  If you experience issues with getting the FTS credentials from the Support Portal, contact your Support Engineer who can assist and provide the URL, username, and password for the upload.

Additional Information

Legacy KB ID

This article was originally published as Attachmate Technical Note 10102.