Version 9.5 SP1
 —  Administration under Windows  —

Tracing webMethods EntireX

This document describes the various techniques available for troubleshooting, tracing and logging with EntireX components.
It covers the following topics:


Table Summarizing Tracing for webMethods EntireX Components

EntireX Component Use Tracing Technique for Tracing Technique
Broker ActiveX Control Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Broker Stubs
EntireX Broker ACI under Windows Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Broker Stubs
EntireX Broker Agent Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Broker Agent
EntireX Broker under Windows Processing within the Broker
Requests to, replies from clients/server
Tracing EntireX Broker
DCOM Wrapper Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Broker Stubs
RPC-related problems on the client side
Requests to, replies from RPC Servers
Requests to, replies from the Broker
Tracing the RPC Runtime
EntireX Java ACI Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing EntireX Java ACI
Java Wrapper Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing EntireX Java ACI
Wrapper for EJB Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Enterprise JavaBeans
Log information to the application server the JavaBean is executing in Logging Enterprise JavaBeans
EntireX Java RPC Server Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Java RPC Server
EntireX IDL Tester    
.NET Wrapper Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Broker Stubs
RPC-related problems on the client side
Requests to, replies from RPC servers
Requests to, replies from the Broker
Tracing the RPC Runtime
C Wrapper Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Broker Stubs
RPC-related problems on the client side
Requests to, replies from RPC servers
Requests to, replies from the Broker
Tracing the RPC Runtime
EntireX RPC Server under Windows RPC-related problems on the server side
Requests to, replies from RPC clients
Requests to, replies from the Broker
Tracing the RPC Server
Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing Broker Stubs
Broker HTTP(S) Agent Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing EntireX Java ACI
EntireX XML/SOAP RPC Server For XML/SOAP RPC Server-related problems. Tracing the XML/SOAP Runtime
Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing EntireX Java ACI
EntireX XML Tester    
EntireX XML/SOAP Listener For XML/SOAP Listener-related problems. Tracing the XML/SOAP Runtime
Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing EntireX Java ACI
XML/SOAP Wrapper For XML/SOAP Wrapper-related problems. Tracing the XML/SOAP Runtime
Transport-related problems
Requests to, replies from the Broker or Broker Agent
Tracing EntireX Java ACI
EntireX RPC-ACI Bridge   Tracing the EntireX RPC-ACI Bridge

Top of page

Tracing EntireX Broker

Start of instruction setTo switch on tracing

Start of instruction setTo switch off tracing

Start of instruction setTo display the trace file (under Windows)

Trace Output

The trace file, BrokerID.LOG, is written to the Broker Directory directory.

Related Information

EntireX Broker Return Codes

Top of page

Tracing Broker Agent

Start of instruction setTo switch on tracing

Start of instruction setTo switch off tracing

Trace Output

The trace output will be written to STDOUT.

If the Broker Agent is started with the System Management Hub, the trace output is written to the subfolder etc of the EntireX main directory. The file name is BrokerAgent.<agent name>.log.

Top of page

Tracing Broker Stubs

Start of instruction setTo switch on tracing for the broker stub

If the trace level is greater than 1, unencrypted contents of the send/receive buffers may be exposed in the trace.

Trace output, file threadid.etb, is written to the trace directory. See Trace Directory.

Start of instruction setTo switch off tracing for the broker stub

Top of page

Tracing Enterprise JavaBeans

Start of instruction setTo switch on tracing

Start of instruction setTo switch off tracing

Trace Output

The trace output will be written to STDOUT.

Start of instruction setTo change the directory and name of the trace destination

Top of page

Logging Enterprise JavaBeans

Start of instruction setTo switch on logging

Start of instruction setTo switch off logging

Log Output

The log output will be written to STDOUT.

Top of page

Tracing EntireX Java ACI

The EntireX Java ACI provides a system property for tracing.

Start of instruction setTo switch on tracing

  1. When starting the Java virtual machine, set the Java system property entirex.trace

  2. The programming interface of the EntireX Java ACI allows you to set the trace value by the Java application using the EntireX Java ACI, see Tracing under Writing Advanced Applications - EntireX Java ACI. There may also be other methods to provide the trace value. See your application documentation.

Start of instruction setTo switch off tracing

Trace Output

The trace output will be written to STDOUT.

Top of page

Tracing Java RPC Server

Start of instruction setTo switch on tracing

Start of instruction setTo switch off tracing

Trace Output

The trace output will be written to STDOUT.

Top of page

Tracing the RPC Runtime

Start of instruction setTo switch on tracing

Start of instruction setTo switch off tracing

Trace Output

By default the trace file, ERXTrace.nnn.log, will be written to the trace directory.

The value nnn can be in the range from 001 to 005.

Start of instruction setTo change the trace destination

Related Information

Environment Variables in EntireX

Top of page

Tracing the RPC Server

Start of instruction setTo switch on tracing

Tracing can also be switched on and off with the environment variable ERX_TRACELEVEL. The settings in the configuration file override the environment variable.

Start of instruction setTo switch off tracing

Trace Output

By default the trace file, ERXTrace.nnn.log, will be written to the trace directory.

The value nnn can be in the range from 001 to 005.

Start of instruction setTo change the trace destination

Related Information

EntireX RPC Server Return Codes

Top of page

Tracing the XML/SOAP Runtime

This section provides information on tracing the following components:

The following topics are covered:

Enabling Tracing

There are two ways to switch on tracing mode:

Using a Property File

Start of instruction setTo switch on tracing mode using a property file

  1. Copy the trace property file entirex.trace.standard to one of the following locations:

  2. Rename the copied file entirex.trace.properties.

  3. Customize entirex.trace.properties as described in Trace Parameters.

  4. If entirex.trace.properties is within the current directory of your client application or your user home directory, it will be located automatically.

    Otherwise, specify the fully qualified or relative file name when starting the Java virtual machine for your client application using property entirex.sdk.default.trace.propertiesfile, example:

    java -Dentirex.sdk.default.trace.propertiesfile ="D:/MyDirectory/entirex.trace.properties" MyClient

Using Trace Parameters of the Java Virtual Machine

Start of instruction setTo switch on tracing mode by specifying the trace parameters of the Java virtual machine

Disabling Tracing

Start of instruction setTo switch off tracing

Configuring a Trace File for the XML/SOAP Listener

We recommend to add the following parameter in file conf/axis2.xml located in the Software AG Common Web Services Stack installation:

<parameter name="exx-trace-propertiesfile">file:///path of trace.properties file</parameter>

Example:

<parameter name="exx-trace-propertiesfile">file:///D:/MyDir/entirex.trace.properties</parameter>

Notes:

  1. If a relative path is specified, the file is located in directory WEB-INF/conf/ in the Web Services Stack web application file that contains the property.
  2. In the parameter section of the file axis2.xml, the value of the parameter exx-trace-propertiesfile can contain definitions of operating system variables, for example location="$EXXDIR/config/entirex.trace.properties".

Configuring a Trace File for the XML/SOAP Wrapper or the XML/SOAP RPC Server

See Enabling Tracing.

Note:
If the XML/SOAP RPC Server is running as a service, enable tracing by adding a Java system property to the start script or by copying file entirex.trace.properties to the same directory as the start script.

Trace Parameters

The following table provides an overview on trace parameters, their respective values, and how to submit them as arguments when invoking the Java virtual machine for the component to be traced.

Parameter Syntax Description
propertiesfile entirex.sdk.component name.trace.propertiesfile= absolute or relative path including the properties file Provide the location of the entirex.trace.properties file. Only used when the component is started.

Note:
A sample trace property file named entirex.trace.standard with predefined trace settings is contained in the directory ../EntireX/config. This file is a model and must be renamed to the valid name when used.

level entirex.sdk.component name.trace.level = tracelevel You can specify the following trace levels:
Keyword Level Description
NONE No tracing Tracing is switch off
STANDARD User Trace invocation of a component.
ADVANCED Expert For support and diagnostics. Expert knowledge of the component is required.
SUPPORT Expert Full trace output. Otherwise, as above.
directory entirex.sdk.component name.trace.directory = absolute or relative path Default is the working directory.
filename entirex.sdk.component name.trace.filename = FILE|STDOUT|STDERR Specify where tracing data is written to:
Keyword Destination
STDOUT (Default) Console
STDERR Console
FILE File name is generated internally: exx.sdk.component name.threadName. backupNo.log , where backupNo is in the range from ".000" to ".009". Note that the number of files created depends on maximumsize. If more than 10 files are required, the oldest backup file is overwritten.
threadoriented entirex.sdk.component name.trace.threadoriented = true | false
Keyword Description
YES Thread-oriented: trace data is distributed over multiple files (one file per thread)
NO (Default) Trace data is written to one file.
rowlength entirex.sdk.component name.trace.rowlength = maximum_characters_per_row Maximum number of characters per row. If this limit is exceeded, the remaining letters are written to a new line.
maximumsize entirex.sdk.component name.trace.maximumsize = max_file_size Maximum size of the log file. If this limit is exceeded, the log file is renamed and the remaining data is written to a new log file, see filename. Note that this specification has an effect only if filename is set to "FILE".
timeframe entirex.sdk.component name.trace.timeframe = number of day Time period after which the log file is closed. If this time limit has exceeded, the log file is renamed and the remaining data (if any) is written to a new log file. Note that this specification has an effect only if filename is set to "FILE". You can specify the following timeframes:
Keyword Description
1-9+H Number of hours
1-9+D Number of days

If no time frame is defined, only one log file is used until tracing is stopped.

Example: If timeframe has been set to 30D, the current log file is closed and renamed at midnight every thirty days, and tracing is continued with a new log file.

Component Names

Trace properties given in the trace property file might have to be restricted by componentname. The following components are available:

EntireX Component componentname Description
  default The trace property is not restricted to a specific EntireX component.
XML/SOAP Runtime xml.runtime The trace property belongs to the EntireX XML/SOAP Runtime only.

Top of page

Tracing the EntireX RPC-ACI Bridge

Start of instruction setTo trace Broker calls

  1. Use the system property entirex.trace=[0|1|2|3].

    This trace does not separate the calls to the Broker for RPC from those to the Broker for ACI. The trace levels are:

  2. Redirect the trace to a file with the property entirex.server.logfile. Set this to the file name of the log file.

Top of page