Log Sink Settings (Velocity)

Article
06/24/2009

[This topic is pre-release documentation and is subject to change in future releases. Blank topics are included as placeholders.]

Microsoft project code named "Velocity" provides the ability to trace events on the cache client and cache host. These events are captured by enabling log sinks in the configuration settings of the client's application configuration file or the cache host's DistributedCache.exe.config file. On the cache client only, you can also configure log sinks programmatically.

Note

We highly recommend that you secure the XML-based application configuration files used to specify the cache client. Data in the cache is not encrypted and is available to any cache client with the appropriate configuration settings.

Configuration Precedence

Both the cache client and cache host have some degree of event tracing set up automatically. But those automatic settings are overridden and ignored if you explicitly specify settings in the fabric element of the application configuration file.

The cache client also has the option of specifying log sink setting programmatically. Programmatic settings always take precedence over anything specified in the application configuration file, even the fabric element.

Default Settings

By default, the cache client and cache host both have log sinks enabled. Without explicitly specifying any log sink configuration settings, each cache client automatically creates a console-based log sink with the event trace level set to Error. If you want to override this default log sink, you can explicitly configure a log sinks.

Without making any changes to the log sink settings automatically configured at installation, each cache host is configured to run a file-based log sink with the event trace level set to Error and an Event Tracing for Windows (ETW)-based log sink with the event trace level set to Verbose.

The default file-based log sink is specified in the log element (a child of the dataCacheConfig element). The default ETW-based log sink is specified in the fabric element. Disabled by default, a console-based log sink element can also be found in the fabric element.

Changing Settings

If you want to change the cache client log sink settings from their default behavior, you must explicitly define log sinks. You can do this programmatically or in your application configuration file by adding a fabric element as specified in the following sections. For more information about how to do this, see How to: Set Log Sink Levels (Code) (Velocity) and How to: Set Log Sink Levels (XML) (Velocity).

If you want to change the cache host log sink settings from their default behavior, there are some options. By using the log element in the dataCacheConfig element, you can change the default file-based log sink's event trace level and the location where it writes the log file. But using that element you cannot configure any other types of log sinks or change the naming convention for the log file names. If you want to make any of these additional changes, you must configure the explicit definitions in the fabric element.

If you want to change a console or ETW-based log sink setting on the cache host, you must locate the corresponding element in the fabric element of the DistributedCache.exe.config file and set the event trace level (the defaultLevel attribute).

If you want to override the default file-based log sink that is described in the dataCacheConfig element, explicitly configure a file-based log sink in the fabric element by inserting an additional customType element for the log sink into the fabric element. This is shown in the fabric element example at the end of this document. The elements and attributes that are required to define all kinds of log sinks in the fabric element are described in the following sections.

Event Classification

Regardless of the approach used to configure log sinks, they all use the same enumeration for classifying the types of the events they capture. This event classification is called the trace level. Both the defaultLevel parameter (when you program) and attribute (in XML) follow the System.Diagnostics.TraceLevel enumeration for specifying trace levels. This enumeration is described in the following table.

TraceLevel Enumeration	Numeric Value	Description
No tracing	-1	No events are captured.
Error	0	Only errors are captured by the log sinks.
Warning	1	Only errors and warnings are capture by the log sinks.
Information	2	Errors, warnings, and information events are captured by the log sinks.
Verbose	3	All event information is captured by the log sinks.

Log Sink Settings

The XML configuration settings for logs sinks are the same for cache clients and cache hosts. Only cache clients have log sink settings configured programmatically. The table in this section shows the log sink settings, where they are located in the XML configuration file, and how they are configured programmatically for the cache client.

In the configuration files, each log sink is specified by a customType element. All are children of the collection element that resides in the fabric element. The fabric element is a child of the configuration element. Programmatically on the client, each sink is defined by the DataCacheLogSink class. Once the log sinks are instantiated, they are enabled by using the CreateLogSinks static method.

There are three types of log sinks available:

Console-based log sinks: Trace events are written to the console.
File-based log sinks: Trace events are written to a file.
ETW-based log sinks: Event tracing for Windows (ETW) is used to trace events.

The settings for each log sink are as follows:

Setting	XML Configuration Location	Code Configuration Location
Log sink class name	The `className` attribute of the `customType` element. This value is always `System.Data.Fabric.Common.` `EventLogger,FabricCommon`.	Indirectly specified when you use the DataCacheLogSink class to define the log sink.
Log sink name (defines type of log sink)	The `sinkName` attribute of the `customType` element. See the table later in this topic for more information of possible values.	Defined with the `sinkType` parameter in the constructor of the DataCacheLogSink class.
Sink Parameter (only the file-based sink requires a parameter)	The `sinkParam` attribute of the `customType` element. This value is an empty string (`""`) for console and ETW-based log sinks. For file-based log sinks, this specifies the naming convention of the log file.	Defined with the `sinkParam` parameter in the constructor of the DataCacheLogSink class. This parameter is not required. For file-based sinks, this specifies the naming convention of the log file.
Log sink trace level	The `defaultLevel` attribute of the `customType` element. Specify the numeric value of the TraceLevel enumeration.	Defined with the `logLevel` parameter in the constructor of the DataCacheLogSink class. Specify this level with the TraceLevel enumeration.

The sinkName attribute of the customType element in the XML configuration file determines what type of log sink will be specified. The following table shows the sinkName attribute values for each log sink type.

Log Sink Type	The `sinkName` Attribute Value
Console-based	`System.Data.Fabric.Common.ConsoleSink,FabricCommon`
File- based	`System.Data.Fabric.Common.FileEventSink,FabricCommon`
ETW-based	`Microsoft.Data.Caching.ETWSink, CacheBaseLibrary`

File Naming Conventions for File-based Log Sinks

The sinkParam parameter is optional for all log sinks, but can be used to support a variety of file naming options for file-based log sinks. In addition to changing the name of the log file, you can also use this parameter to change the location where the log file is written.

There are three parts of the file naming convention for a file-based log sink's sinkParam parameter. These are as follows:

<file path>: (optional) Defines a specified path to where "Velocity" can write the log files.
<file name>: (optional) Defines the customizable name for the log file. The "$" character is a wildcard character that will be replaced with the number of the Windows process identifier (PID) number (as seen in Windows Task Manager).
<date and time formatting>: (optional) defines the points at which a new log file is created and adds date and time values to the file name. A backslash character (/) is used to separate the date and time formatting from the file name value.

Note

When writing to a folder outside the default location, make sure that it has been created and that the application has been granted write permissions. Otherwise, your application will throw exceptions when you enable the file-based log sink.

If a file-based sink is selected and the sinkParam parameter is not used, the default file naming convention is DCacheTrace[$]/dd-hh, where $ is replaced by the PID and dd-hh by the date and time format of "date-hour."

Because a path is not specified by default, this log file is stored in the same folder as the application or host DLL files. An example of this file naming convention is in the following section.

Naming Convention Examples

The following example demonstrates the naming convention; assume that events have been captured by your log sink when the following conditions are true:

The trace events were captured on the tenth day of the month, ten seconds after 9:14am.
You have created a folder, c:\VelocityLogs, and granted the necessary permissions for the application to write there.
When the events were captured, the PID of the application's process was 5188.
The DLLs of your application are running from c:\AppInstallFolder\bin.

The following table shows how various sinkParam parameter settings influence where the log file is written and what the file is named.

`sinkParam` value	Log folder	Log file name
`DCacheTrace[$]/dd-hh` (default value)	`c:\AppInstallFolder\bin`	`DCacheTrace[5188]10-09.log`
`""`	`c:\AppInstallFolder\bin`	`DCacheTrace[5188]10-09.log`
`"DCache/dd-mm"`	`c:\AppInstallFolder\bin`	`DCache10-14.log`
`"MyLogFile/dd-hh-mm-ss"`	`c:\AppInstallFolder\bin`	`MyLogFile10-09-14-10.log`
`"c:\VelocityLogs\$"`	`c:\VelocityLogs`	`5188.log`
`"c:\VelocityLogs\VLog$/dd-hh-mm"`	`c:\VelocityLogs`	`VLog518810-09-14.log`

Note

When specifying file paths in application code, two "\" characters might be necessary to avoid being recognized as an escape character. For example, to specify writing a log file to a folder named logsinkoutput, on a drive named C, the sinkParam parameter is C:\\logsinkoutput\\DCache/dd-mm in application code. In the XML application configuration file, the same path is specified with the sinkParam attribute as C:\logsinkoutput\DCache/dd-mm.

Note

For long-running dd file names, we recommend that you to make file names unique by using the process-specific $ character (for example DCache$/dd). Each process starts a new log file, and appends it, as applicable, to the file naming convention. If you restart your application or a crash occurs, pre-existing log files under that date will be overwritten. Making the file name unique with the process number helps prevent this.

Log Sink Configuration Examples

The example in this section shows an XML-based fabric element that configures Warning event tracing for file-based and console-based log sinks. This element could be put in the application configuration file to enable the corresponding log sinks.

In this example, the log file is saved in the installation folder, with a file name consisting of Dcache and the day, hour, and minute the file was written.

<fabric>
  <section name="logging" path="">
    <!--log sink configuration-->
    <collection name="sinks" collectionType="list">
      
      <!--console-based log sink enabled for warnings and errors -->
      <customType
        className="System.Data.Fabric.Common.EventLogger,FabricCommon"
        sinkName="System.Data.Fabric.Common.ConsoleSink,FabricCommon"
        sinkParam=""
        defaultLevel="1" />
      
      <!--file-based log sink enabled for warnings and errors -->
      <customType
        className="System.Data.Fabric.Common.EventLogger,FabricCommon"
        sinkName="System.Data.Fabric.Common.FileEventSink,FabricCommon"
        sinkParam="Dcache/dd-hh-mm"
        defaultLevel="1" />

      <!--disabled ETW-based sink -->
      <customType
        className="System.Data.Fabric.Common.EventLogger,FabricCommon"
        sinkName="Microsoft.Data.Caching.ETWSink, CacheBaseLibrary"
        sinkParam=""
        defaultLevel="-1" />
      
    </collection>
  </section>
</fabric>

The following example shows the same log sink settings configured for the cache client programmatically. Because the intent is that the ETW-based log sink is disabled, only the file-based and console-based log sinks must be created.

'create a list for the desired log sinks
Dim sinklist As List(Of DataCacheLogSink)
sinklist = New List(Of DataCacheLogSink)(2)

'create file-based log sink, capture warnings and errors
Dim fileBasedSink As DataCacheLogSink
fileBasedSink = New DataCacheLogSink(DataCacheSinkType.FILE, _
                    TraceLevel.Warning, _
                    "DCache/dd-hh-mm")

'create console-based log sink, capture warnings and errors
Dim consoleBasedSink As DataCacheLogSink
consoleBasedSink = New DataCacheLogSink(DataCacheSinkType.CONSOLE, _
                    TraceLevel.Warning)

'add the log sinks to the sink list
sinklist.Add(fileBasedSink)
sinklist.Add(consoleBasedSink)

'enable the sinks
DataCacheFactory.CreateLogSinks(sinklist)

//create a list for the desired log sinks
List<DataCacheLogSink> sinklist = new List<DataCacheLogSink>(2);

//create file-based log sink, capture warnings and errors
DataCacheLogSink fileBasedSink = new DataCacheLogSink(DataCacheSinkType.FILE,
    TraceLevel.Warning, "DCache/dd-hh-mm");

//create console-based log sink, capture warnings and errors
DataCacheLogSink consoleBasedSink = new DataCacheLogSink(DataCacheSinkType.CONSOLE,
    TraceLevel.Warning);

//add the log sinks to the sink list
sinklist.Add(fileBasedSink);
sinklist.Add(consoleBasedSink);

//enable the sinks
DataCacheFactory.CreateLogSinks(sinklist);

Log Sink Settings (Velocity)

Configuration Precedence

Default Settings

Changing Settings

Event Classification

Log Sink Settings

File Naming Conventions for File-based Log Sinks

Naming Convention Examples

Log Sink Configuration Examples

See Also

Tasks

Concepts

Other Resources

Additional resources