Diagnostic Tracing and Message Logging for the SAP adapter
Diagnostic tracing helps to effectively diagnose problems that you might encounter when using the adapters. Adapter clients can activate diagnostic tracing at three levels:
Between the adapter client and the adapter
Within the adapter
Between the adapter and the line-of-business (LOB) application
This section provides information about activating tracing at these levels.
Tracing Between the Adapter Client and the Adapter
Adapter clients can enable WCF tracing to trace issues between the adapter client and the adapter. WCF tracing is used to trace the input XML that comes from the adapter client by using the WCF service model and is useful in diagnosing serialization issues. WCF tracing is not used for the WCF channel model or for output messages from the adapter to the adapter client. You can activate WCF tracing for BizTalk applications and WCF service model applications by adding an excerpt to the respective configuration files. Also, you can enable tracing both at design-time and run-time.
Tracing at design-time. For the design-time experience, you may use the Add Adapter Service Reference Plug-in, Consume Adapter Service Add-in, or the Add Adapter Metadata Wizard. All these tools can be used from Visual Studio. So, to enable tracing for the design-time experience, you must add the excerpt to the devenv.exe.config file located in <installation drive>:\Program Files\Microsoft Visual Studio <version>\Common7\IDE.
Tracing at run-time. For run-time tracing, you must add the excerpt depending on the application you are using.
For a BizTalk Server applications, you must add the excerpt to the BizTalk configuration file, typically BTSNTSvc.exe.config. For BizTalk Server, this file is available typically under <installation drive>:\Program Files\Microsoft BizTalk Server.
For a WCF service model .NET application, you must add the excerpt to the app.config file of your project.
To enable WCF tracing, add the following excerpt within the
<configuration>tag.
<system.diagnostics>
<sources>
<source name ="System.ServiceModel" switchValue="Verbose">
<listeners>
<add name="xml" />
</listeners>
</source>
<source name ="System.ServiceModel.MessageLogging"
switchValue="Verbose, ActivityTracing">
<listeners>
<add name="xml" />
</listeners>
</source>
<source name ="System.Runtime.Serialization" switchValue="Verbose">
<listeners>
<add name="xml" />
</listeners>
</source>
</sources>
<sharedListeners>
<add name="xml" type="System.Diagnostics.XmlWriterTraceListener"
traceOutputOptions="LogicalOperationStack"
initializeData="C:\log\WCFTrace.svclog" />
</sharedListeners>
<trace autoflush="true" />
</system.diagnostics>
<system.serviceModel>
<diagnostics>
<messageLogging
logEntireMessage="true"
logMalformedMessages="false"
logMessagesAtServiceLevel="true"
logMessagesAtTransportLevel="false"/>
</diagnostics>
</system.serviceModel>
This saves the WCF traces to C:\log\WCFTrace.svclog. For more information about WCF tracing, see Tracing.
Important
Make sure you mitigate potential security threats of exposing sensitive business data by enabling tracing. For recommendations see Best practices to secure the SAP adapter.
Tracing Within the Adapter
The adapters log different categories of useful information to the trace file such as errors, warnings, and information messages. Such information is useful in understanding the process flow within the adapter and diagnosing issues with the adapter. You can activate the WCF LOB Adapter SDK and adapter tracing for BizTalk applications and WCF service model applications by adding an excerpt to the respective configuration files. Also, you can enable tracing both at design-time and run-time.
Tracing at design-time. For the design-time experience, you may use the Add Adapter Service Reference Plug-in, Consume Adapter Service Add-in, or the Add Adapter Metadata Wizard. All these tools can be used from Visual Studio. So, to enable tracing for the design-time experience, you must add the excerpt to the devenv.exe.config file located in <installation drive>:\Program Files\Microsoft Visual Studio <version>\Common7\IDE.
Tracing at run-time. For run-time tracing, you must add the excerpt depending on the application you are using.
For a BizTalk Server applications, you must add the excerpt to the BizTalk configuration file, typically BTSNTSvc.exe.config. For BizTalk Server, this file is available typically under <installation drive>:\Program Files\Microsoft BizTalk Server.
For a WCF service model .NET application, you must add the excerpt to the app.config file of your project.
To enable WCF LOB Adapter SDK and adapter tracing, add the following excerpt within the
<configuration>tag.
<system.diagnostics>
<sources>
<source name="Microsoft.ServiceModel.Channels" switchValue="Error">
<listeners>
<add name="xml" />
</listeners>
</source>
<source name="Microsoft.Adapters.SAP" switchValue="Information">
<listeners>
<add name="xml" />
</listeners>
</source>
</sources>
<sharedListeners>
<add name="xml" type="System.Diagnostics.XmlWriterTraceListener"
traceOutputOptions="LogicalOperationStack"
initializeData="C:\log\AdapterTrace.svclog" />
</sharedListeners>
<trace autoflush="true" />
</system.diagnostics>
This saves the WCF traces to C:\log\AdapterTrace.svclog.
Tracing Between the Adapter and the LOB Application
To diagnose issues that you suspect are related to the LOB application, you must enable tracing for communication between the adapter and the LOB application. Adapters also depend on LOB tracing (client/server side) to access this information. The SAP adapter enables adapter clients to turn on tracing within the SAP system by specifying the "RfcSdkTrace" parameter in the connection URI. You must specify this parameter to enable the RFC SDK to trace information flow within the SAP system. For more information about the connection URI, see Create the SAP system connection URI.
Additionally, you can also create an RFC_TRACE environment variable that sets the level of tracing for the RFC SDK. RFC_TRACE is an environment variable defined by SAP and is used by the RFC SDK. If this variable is not defined or is set to 0, the RFC SDK tracing level is bare minimum. If the variable is set to 1 or 2, the tracing level is more detailed.
Note
Irrespective of whether the RFC_TRACE environment variable is set, the RFC SDK tracing is enabled only if the "RfcSdkTrace" parameter is set to true in the connection URI. The value of this environment variable solely governs the level of RFC SDK tracing. If RfcSdkTrace is set to true, the message traces between the adapter and the SAP system are copied to the “system32” folder on your computer. To save the RFC SDK traces to some other location, you can set the RFC_TRACE_DIR environment variable. For more information about these environment variables refer to the SAP documentation.
Viewing the Traces
You can use the Windows Communication Foundation (WCF) Service Trace Viewer tool to view the traces. For more information about the tool, see Using Service Trace Viewer for Viewing Correlated Traces and Troubles.
Configuring Tracking for BizTalk Applications
The BizTalk Server Administration console lets you configure various tracking options for items such as send ports and receive ports. The tracking configuration settings enable you to track inbound and outbound event data, message properties, message bodies, and orchestrations. For more information about configuring tracking for BizTalk applications, see the Managing Artifacts.
You can also use Health and Activity Tracking (HAT) to view historical or tracked data. For more information, see Viewing Historical and Tracked Data.