How To: Configure Local Text Logging Timestamp, Rollover, and Retention

Version Affected: All

 

Overview

Identity Platform's local text logging (the Audit, Debug, Warning, Error, and AuthTrx logs written via the Marvin Formatter and RollingFlatFileTraceListener entries in a realm's web.config) has several settings that can be changed independently: the timestamp format used in each log entry, when a log file rolls over to a new file, and how many rolled-over log files are kept. This article covers all three.

In this article

• Change the Timestamp from UTC to Server Time
• Change the Rollover and Retention Settings
• Special Consideration: GUID-Named Log Files

Change the Timestamp from UTC to Server Time

Starting in Identity Platform 9.2, local text logging uses UTC for its timestamps. Follow these steps to change the timestamp to use the server's local time instead.

1. Open the realm's System Info tab.
2. Scroll down and click to edit the web.config.
3. Search the web.config for {timestamp(yyyy. Each logging formatter entry contains a Timestamp field similar to this:

4. Change {timestamp(yyyy to {timestamp(local:yyyy in that entry:

5. Repeat this change for each of the other logging formatters in the web.config: Audit Marvin Formatter, Debug Marvin Formatter, Error Marvin Formatter, AuthTrx Marvin Formatter, and SysloggerRFC5424.

Once all five entries have been updated, local text logging will show timestamps in the server's local time instead of UTC.

Change the Rollover and Retention Settings

Local text logging uses the standard Microsoft Enterprise Library Logging component and its RollingFlatFileTraceListener, which limits what can be changed. Each log type (Audit, Debug, Warning, and Error) has its own listener entry in the web.config. By default, each one rolls over to a new file 24 hours after it was created and keeps 7 archived files in addition to the file currently being written to — a maximum of 8 files per log type. Because Identity Platform can write to these logs quickly, the default rollover behavior can let a single log file grow large enough that some text editors can no longer open it.

The following settings can be changed on each listener entry:

• rollInterval — Day rolls the file over 24 hours after it was created; Midnight rolls it over at midnight regardless of when it was created.
• rollSizeKB — rolls the file over once it reaches the specified size, in KB.
• rollFileExistsBehavior="Increment" — when using rollSizeKB, add this as well so a second rollover on the same day increments the archived filename instead of overwriting the previous rollover file.
• maxArchivedFiles — the number of archived files kept per log type. A busier realm will fill its archived files faster, so this value may need to be raised to keep the same number of days of history.

To change these settings:

1. Decrypt the web.config for the realm in question and open it in a text editor.
2. Scroll to the <loggingConfiguration> - <listeners> section. Each log type has an entry similar to this default Audit entry:

<add name="Audit Text File" type="Microsoft.Practices.EnterpriseLibrary.Logging.TraceListeners.RollingFlatFileTraceListener, Microsoft.Practices.EnterpriseLibrary.Logging" listenerDataType="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.RollingFlatFileTraceListenerData, Microsoft.Practices.EnterpriseLibrary.Logging" fileName="AuditLogs/Audit.Log" formatter="Audit Marvin Formatter" rollInterval="Day" maxArchivedFiles="7" />

3. Edit the entry using the settings above. For example, to roll Audit log files over at midnight each day and keep 7 archived files:

<add name="Audit Text File" type="Microsoft.Practices.EnterpriseLibrary.Logging.TraceListeners.RollingFlatFileTraceListener, Microsoft.Practices.EnterpriseLibrary.Logging" listenerDataType="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.RollingFlatFileTraceListenerData, Microsoft.Practices.EnterpriseLibrary.Logging" fileName="AuditLogs/Audit.Log" formatter="Audit Marvin Formatter" rollInterval="Midnight" maxArchivedFiles="7" />

Or, to roll Audit log files over once they reach 1 GB in size and keep 7 archived files:

<add name="Audit Text File" type="Microsoft.Practices.EnterpriseLibrary.Logging.TraceListeners.RollingFlatFileTraceListener, Microsoft.Practices.EnterpriseLibrary.Logging" listenerDataType="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.RollingFlatFileTraceListenerData, Microsoft.Practices.EnterpriseLibrary.Logging" fileName="AuditLogs/Audit.Log" formatter="Audit Marvin Formatter" rollSizeKB="1048576" rollFileExistsBehavior="Increment" maxArchivedFiles="7" />

Or, to roll Audit log files over once they reach 1 GB in size, or at midnight if they have not reached 1 GB by then, and keep 7 archived files:

<add name="Audit Text File" type="Microsoft.Practices.EnterpriseLibrary.Logging.TraceListeners.RollingFlatFileTraceListener, Microsoft.Practices.EnterpriseLibrary.Logging" listenerDataType="Microsoft.Practices.EnterpriseLibrary.Logging.Configuration.RollingFlatFileTraceListenerData, Microsoft.Practices.EnterpriseLibrary.Logging" fileName="AuditLogs/Audit.Log" formatter="Audit Marvin Formatter" rollSizeKB="1048576" rollInterval="Midnight" rollFileExistsBehavior="Increment" maxArchivedFiles="7" />

4. Repeat for each of the other log types (Debug, Warning, Error) as needed.
5. Save, then encrypt the web.config again. Repeat these steps for any other realm that needs the same change.

Depending on the activity in the affected realm, changing these settings can reduce the number of days the archived files cover — adjust maxArchivedFiles to a value that suits the realm's actual log volume.

Special Consideration: GUID-Named Log Files

If an Application Pool recycle occurs while a session is actively writing to a log file, Identity Platform can create a new log file named with a Globally Unique Identifier (GUID) instead of the expected Audit/Debug/Warning/Error name. These GUID-named files are not included in the rollover and retention behavior described above — they do not count against maxArchivedFiles and are not removed automatically, so they need to be deleted manually. In the example folder listing below, the files in green follow the normal naming pattern and are included in rotation, while the file in blue is GUID-named and is not.

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.