This document describes the various techniques available for troubleshooting, tracing and logging with EntireX components. It covers the following topics:
Note:
Trace files can contain sensitive personal data (user ID, IP address, SSL certificates and payload data).
This is particularly relevant if you have activated EntireX Security. EntireX uses trace files for accounting, diagnostics
and error analysis.
We recommend you check the different trace opportunities provided by EntireX and delete trace files if they are no longer
needed.
The various EntireX components will not delete these trace files automatically; this is your responsibility as user.
Use the appropriate tools of the respective operating system.
| 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 UNIX | 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 |
| EntireX RPC Server for Java | Transport-related problems Requests to, replies from the Broker or Broker Agent |
Tracing RPC Server for Java |
| 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 | |
| RPC Server | RPC-related problems on the server side Requests to, replies from RPC clients Requests to, replies from the Broker |
Activating Tracing for the RPC Server for C | .NET |
| Transport-related problems Requests to, replies from the Broker or Broker Agent |
Tracing Broker Stubs | |
| EntireX Broker HTTP(S) Agent | Transport-related problems Requests to, replies from the Broker or Broker Agent |
Tracing EntireX Java ACI |
| EntireX RPC Server for XML/SOAP | For RPC Server for XML/SOAP-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 Listener for XML/SOAP | For Listener for XML/SOAP-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 |
See also EntireX Broker Return Codes.
To switch on tracing
Set the attribute TRACE-LEVEL in the broker attribute file
for minimal trace output to "1"
for detailed trace output to "2"
for full trace output to "3"
Example:
TRACE-LEVEL=2
To switch off tracing
Set the attribute TRACE-LEVEL in the broker attribute file to 0:
TRACE-LEVEL=0
Or:
Omit the TRACE-LEVEL attribute.
The trace file, BrokerID.LOG, is written to the Broker Directory.
To view the contents of a log
Using Command Central, select an environment in the Environments pane, select the Instances tab, click the name of a product instance, select the Logs tab, click the log alias for a log in the Alias column.
Or:
Enter the following command in Command Central:
sagcc get diagnostics logs
This retrieves log entries from a log file. Log information includes the date, time, and description of events that occurred
with a specified runtime component.
See Administering EntireX Components with Command Central or the separate Command Central documentation and online help for details.
It is not always convenient to run with
TRACE-LEVEL defined, especially when higher
trace levels are involved. Deferred tracing is triggered when a specific
condition occurs, such as an ACI response code or a broker subtask abend.
Such conditions cause the contents of the trace buffer to be written, showing trace
information leading up the specified event. If the specified event does not
occur, the Broker trace will contain only startup and shutdown information
(equivalent to TRACE-LEVEL=0).
Operating the trace in this mode requires the following additional attributes in the broker
section of the attribute file.
Values for TRBUFNUM and TRAP-ERROR are only examples.
| Attribute | Value | Description |
|---|---|---|
TRBUFNUM |
3 |
Specifies the deferred trace buffer size = 3 * 64 K. |
TRMODE |
WRAP |
Indicates trace is not written until an event occurs. |
TRAP-ERROR |
322 |
Assigns the event ACI response code 00780322 "PSI: UPDATE failed". |
The following methods are available to switch on or off the EntireX Broker trace dynamically. You do not need to restart the broker for the changes to take effect.
etbcmd
Run command utility etbcmd with option -c TRACE-ON or - c TRACE-OFF.
See etbcmd.
Command Central
Use Command Central.
See Updating the Trace Level under Administering the EntireX Broker using the Command Central GUI | Command Line.
To switch on tracing
Set the parameter Trace Option to ON. For the complete table of parameters, see Using the Broker SSL Agent and Using the TCP Agent.
To switch off tracing
Set the parameter Trace Option to OFF.
Or:
Omit the parameter Trace Option.
The trace output is written to STDOUT.
The broker stubs provide an option for writing trace files.
To switch on tracing for the broker stub
Before starting the client application, set the environment variable ETB_STUBLOG:
| Trace Value |
Trace Level | Description |
|---|---|---|
| 0 | NONE |
No tracing. |
| 1 | STANDARD |
Traces initialization, errors, and all ACI request/reply strings. |
| 2 | ADVANCED |
Used primarily by system engineers, traces everything from level 1 and provides additional information - for example the Broker ACI control block - as well as transport information. |
| 3 | SUPPORT |
This is full tracing through the stub, including detailed traces of control blocks, message information, etc. |
Example:
ETB_STUBLOG=2If the trace level is greater than 1, unencrypted contents of the send/receive buffers may be exposed in the trace.
The trace file is created in the current directory. The name is pid.etb where pid is the process ID. If you want to write the trace file to a different location, set environment variable ETB_STUBLOGPATH to the desired path.
See also UNIX Commands to Set the Environment Variables.
Remember to switch off tracing to prevent trace files from filling up your disk.
To switch off tracing for the broker stub
Set the environment variable ETB_STUBLOG to NONE or delete it.
The EntireX Java ACI provides a system property for tracing.
To switch on tracing
When starting the Java virtual machine, set the Java system property
entirex.trace
for minimal trace output to "1"
for detailed trace output to "2"
for full trace output to "3".
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 in the EntireX Java ACI documentation. There may also be other methods to provide the trace value. See your application documentation.
To switch off tracing
Set the Java system property
entirex.trace to 0 when starting the Java virtual
machine
Or:
Omit the Java system property
entirex.trace when starting the Java virtual
machine.
The trace output will be written to STDOUT.
To switch on tracing
When starting the Java virtual machine, set the Java system property
entirex.trace
for minimal trace output to "1"
for detailed trace output to "2"
for full trace output to "3".
To switch off tracing
Set the Java system property
entirex.trace to "0" when starting the Java virtual
machine.
Or:
Omit the Java system property
entirex.trace when starting the Java virtual
machine.
The trace output will be written to STDOUT.
To switch on tracing
Before starting the client application, set the environment variable
ERX_TRACELEVEL to
STANDARD for minimal
trace output
ADVANCED for detailed
trace output
SUPPORT for full trace
output.
To switch off tracing
Set the environment variable to NONE or delete it.
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.
To change the trace destination
Set the environment variable ERX_TRACEFILE to the
desired destination, which can consist of
file names, folder names and variables for file names, folder names, process ID, thread ID, range.
The variables are:
| Variable | Operating System | Description |
|---|---|---|
| %...% | Windows | environment variable |
| $(...) | UNIX | environment variable |
| @PID | UNIX, Win | process ID |
| @TID | UNIX, Win | thread ID |
| @RANGE[ n,m ] | UNIX, Win | m must be greater than n, range is from 0 - 999 |
| @CSIDL_PERSONAL | Windows | The user's home directory. The variable will be resolved by Windows shell functions. |
| @CSIDL_APPDATA | Windows | The Application Data Directory. The variable will be resolved by Windows shell functions. |
| @CSIDL_LOCAL_APPDATA | Windows | The Application Data Directory. The variable will be resolved by Windows shell functions. |
Environment Variables in EntireX
This section provides information on tracing the following components:
EntireX RPC Server for XML/SOAP
EntireX Listener for XML/SOAP
EntireX XML/SOAP Wrapper
The following topics are covered:
Note:
A trace of the XML/SOAP Runtime will trace the XML/SOAP communication. If you need to log the communication of the XML Runtime
with EntireX Broker, see Tracing EntireX Java ACI.
There are two ways to switch on tracing mode:
To switch on tracing mode using a property file
Copy the trace property file entirex.trace.standard to one of the following locations:
the working directory of your client application;
the user's home directory;
any other location.
Rename the copied file entirex.trace.properties.
Customize entirex.trace.properties as described in Trace Parameters.
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 ="/MyDirName/entirex.trace.properties" MyClient
To switch on tracing mode by specifying the trace parameters of the Java virtual machine
Submit the trace parameters when you start the Java virtual machine for the application to be traced. See Trace Parameters. Note that parameter specifications submitted overwrite settings in the property file.
To switch off tracing
Delete or rename the trace property file if it is located in the working directory or in the user's home directory.
Or:
Specify level=NONE when invoking the Java virtual machine :
java -Dentirex.sdk.default.trace.level = NONE MyClient
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">MyDirName/entirex.trace.properties</parameter>
Notes:
exx-trace-propertiesfile can contain definitions of operating system variables, for example location="$EXXDIR/config/entirex.trace.properties".
See Enabling Tracing.
Note:
If the RPC Server for XML/SOAP is running as a daemon, 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.
The following table provides an overview of 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: |
|||||||||||||||
| level | entirex.sdk.component name.trace.level = tracelevel | You can specify the following trace levels:
|
|||||||||||||||
| 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:
|
|||||||||||||||
| threadoriented | entirex.sdk.component name.trace.threadoriented = true | false |
|
|||||||||||||||
| 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:
If no time frame is defined, only one log file is used until tracing is stopped. Example: If timeframe has been set to30D,
the current log file is closed and renamed at midnight every thirty days, and tracing is continued with a new log file.
|
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. |
To trace Broker calls
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:
0 to switch off tracing.
1 to trace Broker calls.
2 to trace Broker calls and the payload.
3 to trace Broker calls and all buffers including the payload.
Redirect the trace to a file with the property
entirex.server.logfile. Set this to the file name
of the log file, the default is standard output.
In some cases a Java trace of the SPM plug-ins is needed to analyze an issue.
To enable Java trace of SPM plug-ins
Stop the Platform Manager. On UNIX it runs as a daemon.
Edit the file custom_wrapper.conf in <Installation Dir>\profiles\SPM\configuration\custom_wrapper.conf. Add the following line:
wrapper.java.additional.<n>=-Dentirex.trace=2
Example:
#encoding=UTF-8 # Configuration files must begin with a line specifying the encoding # of the file. # Put here your custom properties. wrapper.successful_invocation_time=10 wrapper.java.initmemory=32 wrapper.restart.reload_configuration=TRUE wrapper.java.additional.10=-Djava.util.Arrays.useLegacyMergeSort=true wrapper.java.additional.20=-Dentirex.trace=2
In case of issues with SSL, add the line:
wrapper.java.additional.<n>=-Djavax.net.debug=ssl
Example with Java trace and SSL trace:
#encoding=UTF-8 # Configuration files must begin with a line specifying the encoding # of the file. # Put here your custom properties. wrapper.successful_invocation_time=10 wrapper.java.initmemory=32 wrapper.restart.reload_configuration=TRUE wrapper.java.additional.10=-Djava.util.Arrays.useLegacyMergeSort=true wrapper.java.additional.20=-Dentirex.trace=2 wrapper.java.additional.30=-Djavax.net.debug=ssl
Restart the Platform Manager.
The Java trace is written to <installation dir>\profiles\SPM\logs\wrapper.log.Tip:
Search for string "EntireX Java Runtime" for the start of the trace.
To stop the Java trace of SPM plug-ins
Remove the additional lines in <Installation Dir>\profiles\SPM\configuration\custom_wrapper.conf.
Restart the Platform Manager.