Rolling Flat File event sink
.png "patterns & practices Developer Center")
The RollingFlatFileSink class is defined in the Microsoft.Practices.EnterpriseLibrary.SemanticLogging.Sinks namespace. It is included in the Semantic Logging Application Block – Text file sinks package obtainable from NuGet.
The name of the extension method used to create a sink and subscribe it to an event listener is LogToRollingFlatFile.
The method CreateListener in the RollingFlatFileLog class creates an observable listener and a RollingFlatFileSink instance, and subscribes the sink to the listener.
The following table describes the parameters of the LogToRollingFlatFile and CreateListener methods. If you are using the application block out-of-process, you set these parameters using the configuration file for the Out-of-Process Host. See Configuration schema for the out-of-process model for details.
Parameter |
Description |
|---|---|
rollSizeKB |
This is the maximum size the file can reach, in kilobytes, before it rolls over. |
timeStampPattern |
This is the format for the date/time that is appended to the new file name (see the Notes section that follows this table). |
rollFileExistsBehavior |
This parameter determines what happens to an existing file when it rolls over. If you select Increment, the application block creates a new file and names it by incrementing the timestamp. If you select Overwrite the value of the Timestamp Pattern parameter determines if the existing file is overwritten (see the Notes section that follows this table). |
rollInterval |
This parameter determines when the log file rolls over. You can select None (the default), Midnight (in which case the log will roll over at midnight), Minute, Hour, Day, Month, Week, or Year. |
formatter |
The formatter to use with this event sink. The default formatter is the EventTextFormatter. This parameter is optional. |
maxArchivedFiles |
The maximum number of log files to retain. When set to an integer value, the event sink will purge old files based on the file creation date when the number exceeds the specified value (see the Notes section that follows this table). |
isAsync |
This optional parameter specifies if writing to the file should be done synchronously with a blocking call (false, the default) or asynchronously without blocking the UI (true). Asynchronous operation is not configurable in the out-of-process scenario. |
Notes
- If you set the maxArchivedFiles parameter, the event sink will delete (purge) files using the file name pattern **[file-name] *.**file-extension. Therefore, it will delete all log files for any event sink that matches this pattern when it purges archived log files. To prevent this, use a value for the File Name parameter that includes an additional period. For example, use **[file-name].[additional-name].**file-extension.
- You can control the size of the file, its age, or both. For example, if you specify in configuration a rollSizeKB value of 5 and a rollInterval value of Day, the file rolls when its size exceeds 5 KB and it also rolls at the end of the day.
- If you select Increment for the rollFileExistsBehavior parameter, the application block creates a new file when the existing file rolls over. The file name includes the current timestamp. If a file with this name already exists, the application block adds an integer to the end of the timestamp and increments it until it cannot find a file with that name. For example, assume there is a file named mylog2007-01-10.log and the file rolls over while that timestamp is still valid. The sink will then look for a file named mylog2007-01-10.1.log. If no such file exists, it will use that file name for the new file. If that file also exists, it will then attempt to locate the log with the next sequence number mylog2007-01-10.2.log.
- If you select Overwrite for the rollFileExistsBehavior parameter, the sink replaces the existing file with a new file when the current file rolls over. However, if you also set the timeStampPattern parameter, the sink will create a new file with the current time stamp instead of replacing the existing file. If for some reason it cannot overwrite the file, it will generate a name using the same process that is used with the Increment value. The choice of value for the timeStampPattern property affects whether a new file is created. For example, if the rollInterval is set to minute and the timeStampPattern is set to "hh-mm,” a new file is created every minute with the hour and minute appended to the file name. However, if the rollInterval is set to minute and the timeStampPattern is set to "yyyy,” then the log file with the year appended to its name is overwritten every minute. For more information about time stamp patterns, see Custom Date and Time Format Strings on MSDN.
- Relative path names resolve to a location that is relative to the AppDomain.CurrentDomain.BaseDirectory directory.
The following table shows the information that is output by the Rolling Flat File event sink. The formatter used by the Rolling Flat File event sink determines the actual content of the messages. For more information, see Choosing and using text formatters.
Column |
Description |
|---|---|
ProviderId |
A unique identifier for the event source that logged the message. |
EventId |
A unique identifier for this event type. This id is specified using the EventId property of the Event attribute that decorates the log method in your custom event source. |
EventKeywords |
An integer value that represents the value of the Keywords property of the Event attribute that decorates the log method in your custom event source. If multiple Keywords are assigned to a log method, this value represents the result of an OR of the keyword values. |
Level |
The value of the Level property of the Event attribute that decorates the log method in your custom event source. It can be one of Verbose, Informational, Warning, Error, Critical, or LogAlways. |
Message |
This is the formatted message written to the log. It is the value of the Message property of the Event attribute that decorates your log messages in your custom event source, with the placeholders replaced by values from the event payload. |
Opcode |
The value of the Opcode property of the Event attribute that decorates the log method in your custom event source. Valid values are defined by the EventOpcode enumeration. |
Task |
A task identifier. You can optionally assign task identifiers to the log messages in your custom event source by using the Task property of the Event attribute that decorates the log method in your event source. |
Version |
A version number. You can optionally assign a version number to the log messages in your custom event source by using the Version property of the Event attribute that decorates the log method in your event source. |
ProcessId |
The identifier assigned to the process where the event was raised. This value is a nullable Integer. It is available only when the application is running in full trust mode. |
ThreadId |
The identifier assigned to the thread that raised this event. This value is a nullable Integer. It is available only when the application is running in full trust mode. |
ActivityId |
A GUID identifier for the current activity in the process for which the event is involved. |
RelatedActivityId |
A GUID identifier for a related activity in a different process that is related to the current process. |
Payload |
The parameter values passed to the custom log method in your custom event source. These are displayed in JSON format. |
Timestamp |
A timestamp that records when the log message was written. The timestamp includes a UTC offset value. |