Tracing web services

You can trace the web services runtime components, including an unmanaged client, a managed client and a server application. The procedure entry and exit, as well as the processing actions are traceable in the runtime components. You can also trace user-defined exceptions and SOAP messages that use Java™ Message Service (JMS) or HTTP to request web services.

Before you begin

The com.ibm.ws.webservices.engine.*=all=enabled specification traces the web services run time only. See step 4 for settings that you can use to trace user-defined exceptions and SOAP messages or review the tracing SOAP messages with tcpmon documentation to learn about tracing SOAP messages with the tcpmon process.

About this task

The following tasks describe how you can enable trace for web services:

Procedure

  1. Enable trace for a web services unmanaged client.
    1. [AIX Solaris HP-UX Linux Windows][z/OS]Create a trace properties file by copying the %install_root\properties\TraceSettings.properties file to the same directory as your client application Java archive (JAR) file.
    2. [IBM i]Create a trace properties file by copying the app_server_root/properties/TraceSettings.properties file to the same directory as your client application Java archive (JAR) file.
    3. [AIX Solaris HP-UX Linux Windows][z/OS]Edit the properties file and change the traceFileName value to output the trace data. For example, traceFileName=c:\\temp\\myAppClient.trc.
    4. [IBM i]Edit the properties file and change the traceFileName value to output the trace data. For example, traceFileName=/myDir/myAppClient.trc.
    5. Edit the properties file to remove com.ibm.ejs.ras.*=all=enabled and add com.ibm.ws.webservices.engine.*=all=enabled.
    6. Add the -DtraceSettingsFile=<trace_properties_file> option to the java command line that is used to run the client, where trace_properties_file represents the name of the properties file that you created in the substeps a through c. For example, java -DtraceSettingsFile=TraceSettings.properties myApp.myAppMainClass.
  2. Enable trace for a web services-managed client by invoking the launchClient command-line tool with the following options:

    -CCtrace=com.ibm.ws.webservices.engine.*=all=enabled

    -CCtracefile=traceFileName

    For example:
    [AIX Solaris HP-UX Linux Windows][z/OS]
    %install_root%\bin\launchClient MyAppClient.ear
    -CCtrace=com.ibm.ws.webservices.engine.*=all=enabled -CCtracefile=myAppClient.trc
    [IBM i]
    app_server_root/bin/launchClient MyAppClient.ear
    -CCtrace=com.ibm.ws.webservices.engine.*=all=enabled -CCtracefile=myAppClient.trc
    To learn more about this tool, see the launchClient tool information.
  3. Enable trace for a Web Services for Java Platform, Enterprise Edition (Java EE) server application.
    1. Start WebSphere® Application Server.
    2. Open the administrative console.
    3. Click Servers > Application Servers > server.
    4. Click Change Log Detail Levels.
    5. Add or delete the trace string in the text box. For this task, delete the trace string *=info and add the trace string com.ibm.ws.webservices.engine.*=all=enabled. You can specify the trace string in the text box in one of two ways:
      • Type the trace string directly into the text box. You must separate each trace string by a colon (:) with no spaces. For example:
        com.ibm.ws.webservices.trace.MessageTrace=finest:com.ibm.ws.webservices.
        engine.Message=finest
      • Choose a predefined trace string from the section that is listed. The predefined section starts with *[All Components]. The predefined tracing strings web services component are listed under the com.ibm..ws.* section.
        • Click the plus (+) sign to expand the com.ibm.ws.* section.
        • Click the predefined trace string. For example, if you want to add a predefined trace string for the SOAP messaging trace, you can click: com.ibm.ws.webservices.trace.MessageTrace.
        • Click the trace option from the drop-down list. For example, you can choose off, fatal, severe, warning, audit, info, config, detail, fine, finer, finest, and all. The option, finest, is recommended. When you click on the option, the option is added to the end of the trace string. For example:
          com.ibm.ws.webservices.trace.MessageTrace=finest
    6. Click Save and Apply.
    To learn more about enabling trace, see the tracing and logging configuration information.
  4. Enable trace for SOAP messages, user-defined exceptions, or both. The following trace specifications are used to trace SOAP messages:
    • com.ibm.ws.webservices.trace.MessageTrace=all

      This specification traces the contents of a SOAP message, including the binary attachment data.

      When the context-type of the SOAP message is not text and xml, the message probably contains attachments. In this case, the message is displayed in the trace file in the hex dump format. The following example illustrates a line in the hex dump format for non-text SOAP messages:
      0000: 0D 0A 2D 2D 2D 2D 2D 2D - 3D 5F 50 61 72 74 5F 36 ..------=_Part_6
      • In each trace file line, 16 bytes of the message are displayed
      • The first four digits are a hex number whose value is the byte offset into the SOAP message of the first byte on the line.
      • The next 16 two-digit hex numbers are the contents of each of the consecutive bytes in the message.
      • The ASCII representation of the bytes is displayed in the last 16 characters of the line, with unprintable characters that are represented by a period.
    • *=off:com.ibm.ws.webservices.*=all

      You can trace all web services information, including the SOAP messages and the user-defined exceptions, with this setting.

    You can enable logging of user-defined exceptions by specifying the com.ibm.ws.webservices.trace.UserExceptionTrace=all trace string. The user-defined exceptions are not logged by default. A user-defined exception is an exception that is defined in the Web Services Description Language (WSDL) file for an operation.

    A user-defined exception often indicates an error-free condition. For example, the user-defined OverdrawnException exception, can occur for the service endpoint implementation of the makeWithdrawl method. This exception indicates an expected condition and does not indicate an error in the service endpoint implementation. Because these types of exceptions can occur during normal processing, they are not logged by default. When a user-defined exception is logged, the information is sent to the trace.log file and not to the SystemOut.log file.

    Note: 這個主題參照一或多個應用程式伺服器日誌檔。 此外,在分散式和 IBM® i 系統上,另外也建議您可以配置伺服器來使用「高效能可延伸記載 (HPEL)」日誌和追蹤基礎架構,而不使用 SystemOut.logSystemErr.log, trace.logactivity.log 檔案。HPEL 與原生 z/OS® 記載機能也可以一起使用。如果您使用 HPEL,則可以從伺服器設定檔 bin 目錄,利用 LogViewer 指令行工具來存取您所有的日誌和追蹤資訊。請參閱有關利用 HPEL 疑難排解應用程式的資訊,以取得更多使用 HPEL 的相關資訊。
    You can also use the following trace strings to enable tracing for user-defined exceptions, as well as other trace points:
    • com.ibm.ws.webservices.*=all

      Turns on all web services run-time trace logs.

    • com.ibm.ws.webservices.trace.*=all

      Turns on MessageTrace and UserExceptionTrace.

    避免困難 避免困難: Please note once this trace is turned on, the whole SOAP message payload will be written into trace file. If there is any confidential information (such as user ID or password) in the SOAP message as part of the payload, they will be output as plain text as well. Please properly plan to protect the security of your information.gotcha
    Note: For JAX-WS web service, there are two ways (normal level and minimal level) to print out both the Outbound HTTP SOAP message and the Inbound HTTP SOAP message in the trace file.
    Normal level by setting
    com.ibm.ws.websvcs.trace.*=all
    Minimal level by setting
    com.ibm.ws.websvcs.trace.MessageTrace=all:com.ibm.ws.websvcs.trace.LogFilterInputStream=all

Results

You have enabled trace for the unmanaged clients, managed clients, and the server applications. Depending on the trace string specification, the trace can include runtime components, user-defined exceptions and SOAP messages.

What to do next

Analyze the message data.

指出主題類型的圖示 作業主題



時間戳記圖示 前次更新: July 9, 2016 11:18
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=cord&product=was-nd-mp&topic=twbs_tracewbscomp
檔名:twbs_tracewbscomp.html