Information Needed for Troubleshooting

InterSystems IRIS SOAP Log

To log the SOAP calls made to or from an InterSystems IRIS namespace, enable SOAP logging as described here.

To log SOAP calls for a namespace, set nodes of the ^ISCSOAP global in that namespace as follows:

 Set ^ISCSOAP("LogFile")=filename
 Set ^ISCSOAP("Log")=optionString
 Set ^ISCSOAP("LogMaxFileSize")=optionalMaxLogSize

You can also set additional nodes to further fine-tune what is logged:

 Set ^ISCSOAP("LogURL",optionalUrlMatch)=""
 Set ^ISCSOAP("LogJob",optionalJobId)=""
 Set ^ISCSOAP("LogClass",optionalClassname)=""

Where:

• optionString specifies the type of data to include in the log. Use a combination of the following case-sensitive values:

  • i — Log inbound messages.

  • o — Log outbound messages.

  • s — Log security information. Note that this option provides more detail than is generally contained in the SOAP fault, which is intentionally vague to prevent follow-on security attacks.

  • h — Log only SOAP headers. You must combine h with i and/or o. When you use h with i, the log includes only the SOAP Envelope and Header elements for inbound messages. Similarly, when you use h with o, the log includes only the SOAP Envelope and Header elements for outbound messages. The corresponding SOAP Body elements are not logged.

  • H — Log HTTP headers. You must combine H with i and/or o. When you use H with i, the log includes HTTP headers for inbound messages. Similarly, when you use H with o, the log includes HTTP headers for outbound messages. HTTP headers are logged in addition to any SOAP data.

    Note that this option also logs HTTP headers for SOAP messages received by web services within Interoperability productions (that is, received by subclasses of EnsLib.SOAP.ServiceOpens in a new tab),

  You can use a string that contains any combination of these values, for example: "iosh"

• filename is the complete path and filename of the log file to create.

• optionalMaxLogSize is the maximum size of the log file, in bytes. When this maximum is reached, no more entries are written to the log file. This setting is optional.

• optionalUrlMatch is a string that specifies the URL pattern to match. If this option is specified, only traffic using this URL pattern is written to the log. This string can be an exact URL or can include a leading * wildcard, a trailing * wildcard, or both.

  • Example with exact URL: http://localhost:8080/instance/csp/custom/WebService.cls?CfgItem=SoapLogIn

  • Example with leading wildcard : */instance/csp/custom/WebService.cls?CfgItem=SoapLogIn

  • Example with trailing wildcard: http://localhost:8080/instance/csp/custom/WebService.cls

  • Example with both leading and trailing wildcards: /instance/csp/custom/WebService.cls

  Note: To match in all scenarios (client and server), use both leading and trailing wildcards.

  Example:

   Set ^ISCSOAP("LogURL","/instance/csp/custom/WebService.cls")="" 

  

• optionalJobId is the ID of a job (process). This can be the ID of any of the following:

  • The web client process

  • The Web Gateway process running the web service (whether the service is part of a production or not)

    Note that the Web Gateway operates a pool of processes, any one of which might service a request. Also, the Web Gateway may recycle and open new connections and the LogJob setting would need to be updated to follow.

  • The production process, in the case of a web service that is part of a production

  These job IDs can be seen in the Management Portal. If a job ID is no longer valid due to that process stopping, the logging will not automatically delete obsolete job ID entries.

  For example:

   Set ^ISCSOAP("LogJob",15712)=""
   Set ^ISCSOAP("LogJob",16108)=""

  

• optionalClassname is the name of a class. For example:

   Set ^ISCSOAP("LogClass", "WSDL.SoapLog.Service" )=""  // SOAP Client classname
   Set ^ISCSOAP("LogClass", "WSDL.SoapLog.Client.SoapLogServiceSoap" )=""  // SOAP Service classname

  

The log indicates the sender or the recipient as appropriate, so that you can see which web service or client participated in the exchange.

The following shows a partial example of a log file with line breaks added for readability:

01/05/2022 13:27:02 *********************
Output from web client with SOAP action = https://www.mysecureapp.org/GSOAP.AddComplexSecureWS.Add
<?xml version="1.0" encoding="UTF-8" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV='https://schemas.xmlsoap.org/soap/envelope/' 
...
  <SOAP-ENV:Header>
      <Security xmlns="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
   
  </SOAP-ENV:Header>
  <SOAP-ENV:Body>
...
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>


**** Output HTTP headers for Web Client
User-Agent: Mozilla/4.0 (compatible; InterSystems IRIS;)
Host: hostid
Accept-Encoding: gzip


**** Input HTTP headers for Web Client
HTTP/1.1 200 OK
CACHE-CONTROL: no-cache
CONTENT-ENCODING: gzip
CONTENT-LENGTH: 479
CONTENT-TYPE: application/soap+xml; charset=UTF-8
...


01/05/2022 13:27:33 *********************
Input to web client with SOAP action = https://www.mysecureapp.org/GSOAP.AddComplexSecureWS.Add

ERROR #6059: Unable to open TCP/IP socket to server devsys:8080
string

Note the following points:

• With InterSystems IRIS XML tools, you can validate signatures of signed XML documents and decrypt encrypted XML documents. If you perform these tasks in this namespace, the log contains details for them as well. See Using XML Tools.

• The InterSystems IRIS SOAP log captures SOAP calls even when no message is sent on the wire (that is, when the service and client are both on a single machine).

• If a severe error occurs, the system stops writing to the SOAP log. See the messages log instead. For information, see Monitoring Log Files.

• The Task Manager CheckLogging task, which runs every night, creates an alert if SOAP logging is left on for too long (by default, 2 days). Because the SOAP log is voluminous, it is important to pay attention to this alert.

• The SOAPLogContains() method of %SOAP.WebBaseOpens in a new tab reads through the current SOAP log trying to match lines that meet criteria specified by arguments to the method.

HTTP Trace in the Web Gateway

The Web Gateway management page enables you to trace HTTP requests and responses. See Using the HTTP Trace Facility.

Third-Party Tracing Tools

To test your web service, you can use tracing tools such as Wireshark, ProxyTrace, tcpTrace, XMLSpy, soapUI, or Web Service Studio Express. Some of these tools are free and others are licensed. Note that InterSystems does not make any specific recommendations about these tools; they are listed here for your general information.

Tracing tools enable you to see the actual method call, as well as the response. A tracing session listens on a certain port, shows you the messages it receives there, forwards those messages to a destination port, shows the responses, and forwards the responses to the listening port.

For example, suppose you have a web service at https://devsys/csp/mysamples/GSOP.Divide.CLS

And suppose you have a web client that you created to talk to that service. The web client has a LOCATION parameter equal to "https://devsys/csp/mysamples/GSOP.Divide.CLS"

To trace messages between the client and service, you need to do two things:

• In the tracing tool, start a tracing session that listens on port 8080 (for example) and that uses the destination port 52773.

• In the web client, edit the LOCATION parameter to use port 8080 instead of 52773. Then recompile.

  Or, in your code that invokes the web client, change the Location property of the web client:

   //reset location to port 8080 to enable tracing
   set client.Location="https://devsys:8080/csp/mysamples/GSOP.DivideWS.cls"

  

Now when you use the web client, the tracing tool intercepts and displays messages between the client and the web service, as shown in the following example:

The top area shows the request sent by the client. The bottom area shows the response sent by the web service.