Tokens
Description
Tokens are used throughout the Ukadc.Diagnostics libraries - they are a string representation of a particular
PropertyReader. PropertyReaders are an important part of the implementation of the Ukadc.Diagnostics logging system. In short, they read data from the event and allow it to be used in a listener or filter.
The following tokens are built in to Ukadc.Diagnostics:
- {Message} - represents the (potentially formatted) logging message - type: String
- {Id} - the id of the log event - type: Int32
- {ThreadId} - the id of the Thread (ManagedThreadId) - type: String
- {ProcessId} - the id of the process - type: Int32
- {ProcessName} - the name of the process - type: String
- {Callstack} - the callstack - type: String
- {DateTime} - the DateTime of the log event in UTC/Zulu time - type: DateTime
- {LocalTime} - the DateTime of the log event in local time - type: DateTime
- {EventType} - the level of the log event - type: TraceEventType
- {Source} - the name of the trace source that created the log event - type: String
- {ActivityId} - the current activity ID guid (Taken from System.Diagnostics.Trace.CorrelationManager.ActivityId) - type: Guid
- {RelatedActivityId} - the related activity ID as specified when calling TraceTransfer - type: Guid
- {MachineName} - the name of the computer logging the event (from Environment.MachineName) - type:String
- {Timestamp} - the Timestamp of the logging event - type: long
- {PrincipalName} - the Name of the threads Current Principal (note, in ASP.NET applications this will be null until after BeginRequest) - type: string
- {WindowsIdentity} - the Windows Identity name - type: string
The DateTime is also available in parts through a number of other tokens (these tokens are presented as strings primarily to ensure two digit month and date values, e.g. 2008-08-01)
- {Year} - the year of the logging event (YYYY)- type: string
- {Month} - the month of the logging event (MM) - type: string
- {Day} - the day of the logging event (DD) - type: string
- {Hour} - the hour of the logging event (HH) - type: string
- {Minute} - the minute of the logging event (mm) - type: string
- {Second} - the second of the logging event (ss) - type: string
- {Millisecond} - the millisecond of the logging event (ffff) - type: string
It's also possible to specify your own token by creating a custom
PropertyReader:
<ukadc.diagnostics>
<tokens>
<token name="CustomToken" type="YourNamespace.ProcessNamePropertyReader, YourAssembly" />
</tokens>
</ukadc.diagnostics>
Combined Tokens
You can also create a new Token based on the combination of other tokens in a format string. For example:
<ukadc.diagnostics>
<tokens>
<token name="CustomToken" type="YourNamespace.ProcessNamePropertyReader, YourAssembly" />
<token name="CombinedToken" format="{EventType}: {Id}, {Source}, {Message} - {CustomToken}" />
</tokens>
</ukadc.diagnostics>
Now, the {CustomToken} or {CombinedToken} can be specified anywhere that Ukadc.Diagnostics uses propertyTokens. To find our more about PropertyReaders read:
PropertyReader. Note that we even use the {CustomToken} within the {CombinedToken}.
IMPORTANT - It is disallowed to specify both a type attribute and a format attribute on a token element. This will result in an exception.
In some places, a CombinedToken can be specified directly, such as the
OutputDebugStringTraceListener which accepts a format string in its initializeData attribute:
<add type="Ukadc.Diagnostics.Listeners.OutputDebugStringTraceListener, Ukadc.Diagnostics"
name="odsTraceListener" initializeData="{EventType}: {Id}, {Source}, {Message}" />
Note that it is still acceptable to use a token configured within the <tokens /> section of the configuration file, e.g.:
<add type="Ukadc.Diagnostics.Listeners.OutputDebugStringTraceListener, Ukadc.Diagnostics"
name="odsTraceListener" initializeData="{CombinedToken}" />