Logging Configuration
This guide describes how to configure logging settings for PowerTSM components.
Configuration Path
Section titled “Configuration Path”HAKOM:TSM:Http:LoggingConfiguration Structure
Section titled “Configuration Structure”Logging├─ Console│ ├─ LogLevel│ └─ … (see Console below)├─ File│ ├─ LogLevel│ └─ … (see File below)├─ EventLog│ ├─ LogLevel│ └─ … (see EventLog below)├─ ApplicationInsights│ └─ ConnectionString├─ HakomDatabase│ ├─ LogLevel│ └─ … (see HakomDatabase below)└─ CaptureScopesThe specific settings in the brackets are specified in their respective subchapters.
There are four distinct locations that can be logged to:
Console: Writes the logs to the console the API was started in. This is the default.File: Writes the logs to a file.EventLog: Passes the logs to the Windows Event Viewer.HakomDatabase: Saves the logs to a database.
Quick Start
Section titled “Quick Start”Default setting for logging to the console:
<HAKOM> <TSM> <Http> <Logging> <Console> <LogLevel> <Default>Information</Default> </LogLevel> </Console> </Logging> </Http> </TSM></HAKOM>{ "TSM": { "Http": { "Logging": { "Console": { "LogLevel": { "Default": "Information" } } } } }}HAKOM__TSM__Http__Logging__Console__LogLevel__Default=InformationConfiguration Elements
Section titled “Configuration Elements”General Configuration Settings
Section titled “General Configuration Settings”These are the settings that exist regardless of the logging location (Console, File, EventLog).
Path: HAKOM:TSM:Http:Logging:{LoggingLocation}
{LoggingLocation}└─ LogLevel ├─ Default └─ {Category}Log level configuration for a specific provider or category. You can specify Default for the provider’s overall level, or specific categories like Microsoft, System.Net, etc.
Path: HAKOM:TSM:Http:Logging:{LoggingLocation}:LogLevel
| Element | Type | Default | Required | Description |
|---|---|---|---|---|
Default |
LogLevel |
Information |
The default log level for this provider. | |
{Category} |
LogLevel |
— | Category-specific log levels (e.g., Microsoft, System.Net, MyApp.Services). The element name is the category, the value is the log level. Allowed values: Trace, Debug, Information, Warning, Error, Critical, None. |
LogLevel example configuration
Section titled “ LogLevel example configuration”The following fragment shows the HAKOM:TSM:Http:Logging section:
<Logging> <Console> <LogLevel> <Default>Information</Default> <Microsoft.AspNetCore.Routing.EndpointMiddleware>Critical</Microsoft.AspNetCore.Routing.EndpointMiddleware> <Microsoft.AspNetCore.Hosting.Diagnostics>Warning</Microsoft.AspNetCore.Hosting.Diagnostics> <Microsoft.Hosting.Lifetime>None</Microsoft.Hosting.Lifetime> <HAKOM.Cryptography.Core.Net.Api.ICryptographyService>None</HAKOM.Cryptography.Core.Net.Api.ICryptographyService> </LogLevel> </Console></Logging>See the .NET documentation for the possible LogLevel values.
Specific Configuration Settings
Section titled “Specific Configuration Settings”These settings are specific to the location that should be logged to.
Console
Section titled “Console”Path: HAKOM:TSM:Http:Logging:Console
Console├─ FormatterName└─ FormatterOptions ├─ ColorBehavior ├─ SingleLine ├─ IncludeScopes ├─ TimestampFormat └─ UseUtcTimeStampThis logger is of the type Microsoft.Extensions.Logging.Console.SimpleConsoleFormatter and should be configured as such.
See the .NET documentation for the available formatter options.
Path: HAKOM:TSM:Http:Logging:File
File├─ QueueSize├─ FinalFlushGracePeriod├─ TimeToWaitForOpenSlot├─ MaxFileSize├─ Append├─ Path├─ FileNameTemplate├─ FileNameTimeStampFormat├─ FileNameTimeStampType├─ TimeStampFormat├─ TimeStampType└─ EncodingThis logger is specific to PowerTSM.
| Element | Type | Default | Required | Description |
|---|---|---|---|---|
LogLevel |
LogLevel |
Information |
Sets the minimum log level for which messages should be written to the file. | |
QueueSize |
int |
1024 |
Defines how many messages can be written to the queue before additional messages have to wait for previous messages to be written to disk. | |
FinalFlushGracePeriod |
TimeSpan |
1.5ms × QueueSize |
Defines how long to wait for all remaining messages in the queue to be written to disk before disposing of the logger. | |
TimeToWaitForOpenSlot |
TimeSpan |
100μs × QueueSize |
Defines how long to wait for the queue to be ready for additional messages. If messages can’t be written within this time, they will be lost. Consider increasing QueueSize if this occurs frequently. |
|
MaxFileSize |
uint |
4194303 |
Defines a limit for the size of log files in kilobytes (default ≈ 4 GB). Once exceeded, a new file will be created. | |
Append |
bool |
true |
Defines if existing content should be replaced (false) or appended to (true). |
|
Path |
string |
. |
The path in which log file(s) should be created. Environment variables may be used (e.g., %HOMEPATH%\logs). To specify a relative path, start with .\. See the example below. |
|
FileNameTemplate |
string |
{host}.{processName}.{timeStamp}.log |
Template for log file names. Placeholders: {timestamp}, {host}, {processId}, {processName}. |
|
FileNameTimeStampFormat |
string |
yyyyMMdd\THHmm |
Format string for the {timestamp} placeholder in file names. See format strings docs. |
|
FileNameTimeStampType |
DateTimeKind |
Local |
Whether to use local time or UTC for the file name timestamp. | |
TimeStampFormat |
string |
yyyy-MM-dd\THH\:mm\:ss.fffzzz |
Format string for the timestamp prepended to each log message. See format strings docs. | |
TimeStampType |
DateTimeKind |
Local |
Whether to use local time or UTC for log message timestamps. | |
Encoding |
Encoding |
UTF8 |
The text encoding to use in the log file. |
File logger example configurations
Section titled “ File logger example configurations”The following fragments show the HAKOM:TSM:Http:Logging section:
<Logging> <Console> <LogLevel> <Default>Information</Default> </LogLevel> </Console> <File> <Path>.\logs</Path> <FileNameTemplate>TSM_{host}.{processName}.{timestamp}.log</FileNameTemplate> <LogLevel> <Default>Information</Default> </LogLevel> </File></Logging><Logging> <Console> <LogLevel> <Default>Information</Default> </LogLevel> </Console> <File> <Path>%HOMEPATH%\TSM\logs</Path> <FileNameTemplate>TSM_{host}.{processName}.{timestamp}.log</FileNameTemplate> <LogLevel> <Default>Information</Default> </LogLevel> </File></Logging>EventLog
Section titled “EventLog”This logger sends its messages to the Windows Event Viewer.
Path: HAKOM:TSM:Http:Logging:EventLog
EventLog├─ LogName├─ SourceName└─ MachineNameThis is a logger by .NET. Required settings are LogName and SourceName. The values of these two properties also must be registered through PowerShell.
Quick rundown of Event Viewer logger usage
Section titled “ Quick rundown of Event Viewer logger usage”Register LogName and SourceName through PowerShell in administrator mode:
New-EventLog -LogName "myLogName" -Source "mySourceName"Add the configuration entry under HAKOM:TSM:Http:Logging (minimal example):
<EventLog> <LogLevel> <Default>Information</Default> </LogLevel> <LogName>myLogName</LogName> <SourceName>mySourceName</SourceName></EventLog>Open the log through the Windows search bar: Event viewer > Application and Service Logs > myLogName.
See the .NET documentation for all EventLog settings.
HakomDatabase
Section titled “HakomDatabase”Path: HAKOM:TSM:Http:Logging:HakomDatabase
HakomDatabase├─ Repository├─ QueueSize├─ TimeToWaitForOpenSlot└─ FinalFlushGracePeriodThe database logger is currently only available through the PowerTSM .NET API. Implementation for the PowerTSM HTTP API is intended.
Important Notes
Section titled “Important Notes”Database Exception Details
Section titled “Database Exception Details”Database exceptions (for example HK12030) intentionally omit sensitive details such as the failing database command and its parameters from the exception message returned to callers, following Microsoft’s guidelines on not exposing sensitive information through exception messages.
When logging is enabled, these additional details — including the inner exception’s Data entries — are written to the log instead, which makes diagnosing database problems considerably easier.