WCF trace configuration and trace file names
When trace is fully enabled, it produces two output files, one for diagnosing WCF problems, and one detailed file for internal trace diagnostic material. To simplify trace enablement, both the .NET 3 TraceSource and XMS .NET trace stacks use a single interface.
Two different trace methods are available for the WCF custom channel, the two trace methods are activated independently or together. Each method produces its own trace file, so when both trace methods have been activated, two trace output files are generated.
To keep the configuration and enablement as simple as possible, the same interface is used to control both trace methods. The app.config file must be edited to include the relevant trace configuration as described in the following section. Users can then add their own equivalent sections to combine the output with trace from their own application.
WCF custom channel tracing is not enabled by default. You must first create a trace listener, then set the required trace level for the selected trace source in the app.config file.
Configuring WCF custom channel with WCF infrastructure trace
<system.diagnostics><sources>
section
in the app.config file:<source name="IBM.XMS.WCF" switchValue="Verbose,ActivityTracing">
<listeners>
<remove name="Default"/>
<add name="NewListener"/>
</listeners>
</source>
The preceding piece of code makes the channel
trace using the .NET 3 TraceSource. All invocations of the configuration
files associated with the executable files are controlled by this
piece of code.Configuring WCF custom channel with XMS .NET trace
Configuring
the XMS .NET trace requires that you add a section of code to the <system.diagnostics><sources>
section
in the app.config file. However, the piece of
code is added to the extensible <source>
element
shown in the Configuring WCF custom channel with WCF infrastructure trace section. So
although the WCF infrastructure trace code must be present for the
XMS .NET trace to work, the WCF infrastructure trace can be disabled
if it is not required, as described in the
Enabling WCF trace section.
<source name="IBM.XMS.WCF" switchValue="Verbose, ActivityTracing"
xmsTraceSpecification="*=all=enabled" xmsTraceFilePath="path"
xmsTraceFileSize="2000000" xmsTraceFileNumber="4" xmsTraceFormat="advanced">
<listeners>
<remove name="Default"/>
<add name="NewListener"/>
</listeners>
</source>
WCF trace configuration variables
Variable | Description |
---|---|
name | Specify the name as: IBM.XMS.WCF |
switchValue | The switchValue controls the trace level. When switchValue is set to Off, the WCF infrastructure TraceSource is not generated. Any other value, such as Verbose, generates TraceSource. For detailed trace level information from Microsoft, consult your WCF documentation or go to the Microsoft WCF Tracing web page: https://msdn.microsoft.com/en-us/library/ms733025(vs.85).aspx |
xmsTraceSpecification=ComponentName=type=state | ComponentName is the name
of the class that you want to trace. You can use a * wildcard character
in this name. For example: specifies
that you want to trace all classes, and specifies
that you require API trace only. type can be
any of the following trace types:
state can be either enabled or disabled.
|
xmsTraceFilePath="filename" | If you do not specify an xmsTraceFilePath, or
if the xmsTraceFilePath is present but contains an empty string, then
the trace file is placed in the current directory. To store the trace
file in a named directory, specify the directory name in the xmsTraceFilePath,
for example:
|
xmsTraceFileSize="size" | The maximum allowed size of the trace file.
When a file reaches this size, it is archived and renamed. The default
maximum is 20 KB, which is specified as:
|
xmsTraceFileNumber="number" | The number of trace files that are to be retained. The default is 4 (one active file and three archive files). The minimum number allowed is two. |
xmsTraceFormat="format" | There are two levels of xmsTraceFormat: basic and advanced.
The default trace format is basic if you do not specify an xmsTraceFormat,
or if the xmsTraceFormat is present but contains an empty string.
Trace files are produced in this format if you specify: If
you require trace that is compatible with trace analyzer tools, you
must specify:
|
Enabling WCF trace
There are four combinations for enabling and disabling the two different trace methods. The four combinations require editing the values of the sections of coded described in the preceding sections.
There is also an environment variable that can be set; for more information see Enabling WCF trace with the WCF_TRACE_ON environment variable.
Trace type | Value changed | Example |
---|---|---|
XMS trace enabled. WCF TraceSource enabled | The switchValue is not set
to Off |
|
XMS trace enabled. WCF TraceSource disabled | The switchValue is set to Off and
an xmsTraceSpecification has been given |
|
XMS trace disabled. WCF TraceSource enabled | There are two ways to achieve this result:
|
|
XMS trace disabled. WCF TraceSource disabled | There are three ways to achieve this result:
|
|
Enabling WCF trace with the WCF_TRACE_ON environment variable
As well as the preceding methods described to enable WCF trace, the XMS .NET trace can also be enabled using the WCF_TRACE_ON environment variable.
Setting the WCF_TRACE_ON environment variable to any non-null value is the equivalent of setting the xmstraceSpecification to *=all=enabled, for example: "set WCF_TRACE_ON=true"
However, if the xmstraceSpecification is explicitly set in the app.config file, then the WCF_TRACE_ON environment variable is overridden.
WCF trace output files and file names
XMS trace files are traditionally named using the base name and process ID format of: xms_trace_pid.log, where pid is the process ID.
As XMS trace files can still be produced in parallel with WCF custom channel trace files, the WCF custom channel trace integrated with XMS .NET trace output files have the following format to avoid confusion: wcfxms_trace_pid.log, where pid is the process ID.
The trace output file is created in the current working directory by default, but this destination can be redefined if necessary.