K2 Host Server logging

To troubleshoot issues in the hosted services inside the K2 service, you can run the K2 application service in console mode and/or enable logging output with various output targets and levels of verbosity. Several standard logging providers are available in K2, and you can create customized extensions to fit your needs. You can also choose which extensions are active and the message severity level (LogLevel) that is logged. To change the K2 server logging configuration, edit the logging extension properties in the HostServerLogging.config file in the [Program Files]\K2\Host Server\Bin folder.

There are really only two sections of the HostServerLogging.config file you will need to modify to configure. logging. For most situations, you need only set the specific log destination’s Active flag to true or false, and specify the severity of messages to log. In rare circumstances, you may need to modify the appSettings section of the file, particularly to disable asynchronous queuing and to include a stack trace.

By default, console logging is turned on, but at the “Info” severity level. Thus, if you start K2 server in console mode without modifying the HostServerLogging.config file, you will see Informational, Warning, and Error messages. File-based logging is turned off by default.

The two most common forms of logging are “to Console” and “to File”. Logging to the console is very useful for troubleshooting and validating general issues. However, from a performance perspective, logging to the console has high overhead, and should only be enabled when needed. Similarly, logging to file has some additional overhead. It is therefore recommended to only log “All” events to file during periods of troubleshooting. For more regular monitoring purposes, you should scale back file-based logging to only log events of severity Warning or higher.
If you edit the logging configuration, you must restart the K2 server for the changes to take effect.

Host Server logging is typically useful for troubleshooting

  • Service startup failures
  • Authentication failures
  • Communication issues
  • Verifying that Actions are being sent to the K2 Server (and the correct K2 Server)
  • Verifying that Workflows are being processed

K2 writes the Host Server logs to the [Program Files]\K2\Host Server\Bin folder by default. The default file name is HostServer.log with the timestamp and cycle number appended to the name.

  • Timestamp: this is the date the file was created and is in the format YYMMDD. For example: 190618 is June 18th, 2019.
  • Log cycle: this is a sequential number for logs created on the same day. The system creates a new log file when the current log file reaches a configured size, or when it has been in use for a certain amount of time. The File logging extension section below describes these settings. For example, the second log created on the 18th of June 2019 would have the file name: HostServer190618_2.log

The default location of the file is: "%ProgramFiles%\K2\Host Server\Bin\HostServerLogging.config". It is a standard XML file and you can use a text editor to edit it.

There are 5 sections to the configuration file that apply to logging:

This topic describes logging defaults. These defaults are the recommended level of logging. You should adjust default logging if you understand the impact of doing so, and typically only for the duration of the troubleshooting task. Contact K2 Product Support services if you need assistance with configuring logging or interpreting log output.
Backup the config file so that you can restore the defaults when you finish troubleshooting.

The settings in the appSettings section of the K2 server's logging configuration file determine what events K2 logs. This following block shows the attributes in the appSettings section of the logging configuration file:

Copy

AppSettings configuration

<appSettings>
    <!-- Set Date format-->
    <add key="DateFormat" value="yyyy-MM-dd HH:mm:ss" />
    <!-- Set base Log Level; should be "All"-->
    <add key="LogLevel" value="All" />
    <!-- Create Checksum/Hash for each row in logfile -->
    <add key="RowHash" value="False" />
    <!-- Adust Logger Thread Priority Low/Normal/High -->
    <add key="ThreadPriority" value="Low" />
    <!-- Enable/Disable Async Queueing True/False-->
    <add key="AsyncQueueEnabled" value="True" />
    <!-- Message Logged was an Exception, Include Stack Trace -->
    <add key="IncludeStackTrace" value="True" />
    <!-- Preserve Log Files SequenceNumber between restarts -->
    <add key="PreserveSequence" value="True" />
    <!-- Add GUID per log entry -->
    <add key="AddGUID" value="True" />
    <!-- Set MSMQ Path-->
    <add key="MSMQActive" value="false" />
    <add key="MSMQPath" value=".\private$\SCQueue" />
</appSettings>
Setting Name Description Default
DateFormat Define the output format for the date/time stamp on events yyyy-MM-dd HH:mm:ss
LogLevel

Sets the default log level (you can override log levels for each log output, if desired). There are five severity levels. The five levels, in order of severity (highest to lowest) are:

  • Error
  • Warning
  • Info
  • Debug
  • Ignore

The K2 Host Server will log messages with at least the severity level specified, to the defined destination. So, based on the list above, setting the severity level to “Info” will result in all Info, Warning, and Error messages being logged.

 All
RowHash Specify whether to create Checksum/Hash for each row in log file. Typically used to detect if the log outputs was modified after being generated. False
Thread Priority

Adjusts the logging thread priority. Valid values are: 

  • Low
  • Normal
  • High

Normal or High priority can negatively impact performance, but if you encounter issues where the K2 service stops, you may want to enable high-priority logging to capture log output immediately before the service stops.
 *1 Low
AsyncQueue Enabled

Define whether asynchronous queuing is enabled.

By default, K2 performs logging asynchronously. This means that the K2 Host Server continues without waiting for confirmation that the message was successfully logged. Disabling asynchronous queuing prevents K2 from performing any additional action until receiving confirmation that the event has been logged. Use this while troubleshooting, to ensure that all possible logging is received. Disabling asynchronous queuing can have a performance impact on your server(s). K2 recommends you only disable asynchronous queuing during troubleshooting.

 *2 True
IncludeStack Trace

If the message logged was an exception, you can choose to include the stack trace. Including the stack trace is recommended when troubleshooting issues where the K2 service stops unexpectedly. If you are experiencing unhandled exceptions in K2, leading to server/service crashes, you may be asked by K2 Support to enable the Stack Trace feature of logging. This will include a stack trace at the time the exception occurs. You will have to disable asynchronous queuing to enable the stack trace functionality.

 *3 True
Preserve Sequence Define whether to preserve the log file SequenceNumber between restarts. By default, K2 names Host Server log files using the format HostServer +[Date]+ _ +[sequence number]+.log. Every service restart on the same date increments the sequence number. *4 True
AddGUID Whether to add a unique GUID per log entry. Typically used if you want to export log output to something like a database. True
MSMQActive (Legacy) Whether MSMQ is available as a logging option. This is a legacy setting that is no longer used in K2 Five. false
MSMQPath (Legacy) Set MSMQ Path for MSMQ-based logging. This is a legacy setting that is no longer used in K2 Five. .\private$\SCQueue

You can enable each logging extension (destination) individually, with its own level of logging output. This allows you, for example, to log Error messages to the Event Log, but Warning and higher messages to file.

Copy

This code block shows the default log level settings

<ApplicationLevelLogSettings>
  <ApplicationLevelLogSetting Scope="Default">
    <LogLocationSettings>
      <LogLocation Name="ConsoleExtension" Active="True" LogLevel="All" />
      <LogLocation Name="FileExtension" Active="True" LogLevel="Error" />
      <LogLocation Name="EventLogExtension" Active="True" LogLevel="Error" />
      <LogLocation Name="ArchiveExtension" Active="False" LogLevel="Debug" />
      <LogLocation Name="MSMQExtension" Active="False" LogLevel="Debug" />
    </LogLocationSettings>
  </ApplicationLevelLogSetting>
</ApplicationLevelLogSettings>
  • Enable or disable the logging for an extension by setting the Active attribute to True or False respectively.
  • Output of information to the Windows event log is enabled by default using the EventLogExtension. The Windows event log can expose logging information regarding network connections, authentication issues, underlying OS issues and more.
  • K2 manages the incoming messages and depending on what the ApplicationLevelLogSetting attribute is set to, determines which messages are logged to the extension or extensions that have been set to active. If you set the attribute to Info, then K2 logs all messages from Info (for example, notification that a service has started), Warning and Error. However, if you set just for Errors then K2 only logs and writes errors to the selected extension. The log level in the table below are arranged in order from most detail logged (ALL) to least detail logged (Error).
Log level Description
All Logs all events. This would put more strain on the system than the debug level and is also not recommended unless necessary.
Debug Logs all items that assist with troubleshooting. K2 recommends you don't use the debug level unless you specifically need to debug something to track a problem. This is because the log files will grow very quickly and due to the volume of log entries, there would be a severe performance impact on the server.
Info Non critical items. Provides operational messaging for the Administrator to view system operation.
Warning Items that will not prevent the system from functioning. These may cause issues or errors in time.
Error Only logs critical events where a service or resource fails or is unreachable.

You can also change this section to filter the logged messages by namespace. By adding <ApplicationLevelLogSetting> sections with a scope other than Default, you can override the default logging level for certain namespaces. This allows you to set a more restrictive logging level for some namespaces, thus reducing the messages you consider chatter. This helps both to reduce the size of log files (or database tables) and to simplify troubleshooting by weeding out unnecessary messages. Below is an example of how to do this.

Copy

ApplicationLevelLogSetting

<ApplicationLevelLogSetting Scope="SourceCode.Hosting">
  <LogLocationSettings>
    <LogLocation Name="ConsoleExtension" Active="True" LogLevel="Error" />
    <LogLocation Name="FileExtension" Active="True" LogLevel="Error" />
  </LogLocationSettings>
</ApplicationLevelLogSetting>
<ApplicationLevelLogSetting Scope="SourceCode.Workflow.Runtime.ClientConnection">
  <LogLocationSettings>
    <LogLocation Name="ConsoleExtension" Active="True" LogLevel="Error" />
    <LogLocation Name="FileExtension" Active="True" LogLevel="Error" />
  </LogLocationSettings>
</ApplicationLevelLogSetting>
<ApplicationLevelLogSetting Scope="SourceCode.Workflow.Runtime.SocketListener">
  <LogLocationSettings>
    <LogLocation Name="ConsoleExtension" Active="True" LogLevel="Error" />
    <LogLocation Name="FileExtension" Active="True" LogLevel="Error" />
  </LogLocationSettings>
</ApplicationLevelLogSetting>
<ApplicationLevelLogSetting Scope="SourceCode.EventBus">
  <LogLocationSettings>
    <LogLocation Name="ConsoleExtension" Active="True" LogLevel="Error" />
    <LogLocation Name="FileExtension" Active="True" LogLevel="Error" />
  </LogLocationSettings>
</ApplicationLevelLogSetting>

There are four different types of logging available out of the box in K2 Five. You can choose to log to any, all, or none of them. The five available types of logging are:

You can also write custom logging extensions to output log information to a third-party like an enterprise-level system monitoring application. For more information see the Custom Logging Extensions topic in the K2 Five Developers Reference.

This code block shows the extensions available, along with properties for each extension (see the headings below for more on the configuration settings for each extension):

Copy

Logging extensions

<Extensions>
  <Extension Name="ConsoleExtension" type="SourceCode.Logging.Extension.ConsoleExtension">
    <Property Name="Shorthand" value="true" />
  </Extension>
  <Extension Name="EventLogExtension" type="SourceCode.Logging.Extension.EventLogExtension" />
  <Extension Name="FileExtension" type="SourceCode.Logging.Extension.FileExtension">
    <Property Name="LogFileName" value="HostServer.log" />
    <Property Name="LogFilePath" value="" />
    <Property Name="HashAlgorithm" value="CRC32" />
    <Property Name="MaxFileSizeKB" value="5000" />
    <Property Name="MaxLifetimeSpan" value="0:0:0:00" />
  </Extension>
  <Extension Name="MSMQExtension" type="SourceCode.Logging.Extension.MSMQExtension">
    <Property Name="QueuePath" value=".\private$\SCQueue" />
  </Extension>
  <Extension Name="ArchiveExtension" type="SourceCode.Logging.Extension.ArchiveExtension">
    <Property Name="HostServerConfigFileName" value="K2HostServer.exe.config" />
    <Property Name="ConfigDBConnectionName" value="HostserverDB" />
  </Extension>
</Extensions>

Each logging extension (destination) can be enabled individually, with its own level of logging output. This allows you, for example, to log Error messages to the Event Log, but Warning and higher messages to file. The ApplicationLevelLogSettings node of the configuration file determines the “Active” (True/False) state of each logging location, as well as the level of messages logged to that location (e.g. All, Error, Info, Debug, Warning). Example: 

Console logging extension (ConsoleExtension)

Run the K2 Host Server in console mode to see real-time activity in K2 Host Server. This is useful when troubleshooting performance issues, authentication issues and issues when K2 service fails to start.

To start K2 in console mode, stop the K2 Windows service and then launch console mode with the K2 Server (Service Account) shortcut on the Start Menu. It is recommended to start K2 Console in the context of the K2 Service Account to preserve the same credentials used when the K2 service runs as a Windows service. This will help to prevent false issues, since the user context is the same for both Console and Service modes.

Using the console does not record the log and when you close the console, you lose the log.

The following Property settings are available for the Console logging extension:

Setting Name Description Default
Shorthand

You can view the console log in shorthand mode or deactivate shorthand mode to see the event timestamp

Valid values are true or false

This image shows the console when the Shorthand value is set to true.

Setting the value to false includes the timestamp but makes the log harder to read.

 true

File logging extension (FileExtension)

The file logging extension writes text files to a specified location. You can configure setting such as the file name, output folder, and maximum file size and/or lifespan.

The following Property settings are available for the File logging extension:

Setting Name Description Default
LogFileName

Set the default name of the generated log files. An example of the file name for a Host Server log:
HostServer190720_1.log

 HostServer.log
LogFilePath Set the path where the logfiles should be generated, e.g. C:\K2LogFiles (empty, which creates the log file in log file in the same folder as the HostServerLogging.config file ([Program Files]\K2\Host Server\Bin)
HashAlgorithm The algorithm to use when generating the hash if the RowHash setting is enabled. CRC32
MaxFileSizeKB The maximum size of a log file before the next file is created. If this value is 0, the log file will not have an upper file size limit. 0
MaxLifetimeSpan The time duration before a new log file is created, in for the format d:h:m:ss. For example 1:0:0:00 will create a new log file every day. 0:0:0:00
If both MaxFileSizeKB and MaxLifetimeSpan are set, whichever setting is reached first will be applied. It is recommended to set a maximum file size as well as a maximum lifetime span to avoid very large text files

Windows Event log extension (EventLogExtension)

This extension handles the event logging to the Windows Event Viewer and has no properties. You can change the log level reported by changing values in the Application Level Log settings described below.

Microsoft Message Queue extension (MSMQExtension)

(This is a legacy extension and is no longer used.)

Archive extension

The archive extension logs data to the [HostServer].[LogArchive] table in the K2 database. This database table is available for queries and you can access it either manually using the SQL Server Management Studio or through a SmartObject using the SQL Service Type. Typically, you may use the Archive extension if you want to be able to run queries on the log output, or if you have multiple K2 application servers that need to output logging information to a central location.

This code block shows the configuration settings for the archive extension. Do not change the values for either property.

The table below explains each field in the [HostServer].[LogArchive] table.

Table column Data type Description
MessageTimestamp DateTime K2 generates the MessageTimestamp as the message is being logged.
MessageID Int64 The ID of the message as defined inside the HostServerLogging.config file, in the <MessageList> element. For example, MsgID="1001" is an Info message indicating ServerStarted.
MessageCategory

MessageName

MessageSeverity

MessageString 		String

String

Severity

String		 These four items correspond to the elements in the HostServerLogging.config file and are based off the MessageID. The MessageString may contain parameters provided by the caller, for example, the domain account in this message: 1001 Host Server Started as DENALLIX\K2service
MessageSource String The caller provides the MessageSource, which indicates the area of code that the message originates from. This should typically be the namespace and class.method of the calling code. For example: SourceCode.Hosting.Server.Runtime.HostTypeLoader
MessageIdentity MessageIdentityObject MessageIdentity contains two items; MessageUser and MessageUserIP. The calling code should provide these, when available. MessageUser is the user who is currently logged on and MessageUserIP is his or her IP Address.
MessageHost String This is a legacy field and only useful when using MSMQ. MessageHost is set by K2 and used to indicate the server name of the originating HostServer.
MessageOriginalSeqNum UInt64 This is a legacy field and only useful when using MSMQ. MessageOriginalSeqNum shows the message's original sequence number from where the message originated from.
This section is here only to illustrate the rest of the HostServerLogging.config file, you should not change any of these settings.

Events logged by the system fall into several categories. The list of categories is in the CategoryList section of the HostServerLogging.config file and listed is this code box:

Copy

Log event categories

<CategoryList>
  <Category CatID="0" Name="General">General Events</Category>
  <Category CatID="1" Name="System">System Events</Category>
  <Category CatID="2" Name="Client">Client Events</Category>
  <Category CatID="3" Name="Security">Security Events</Category>
  <Category CatID="4" Name="Communication">Communication Events</Category>
  <Category CatID="6" Name="SmartFunctions">SmartFunctions</Category>
  <Category CatID="7" Name="Authorization Provider">Authorization Provider</Category>
  <Category CatID="8" Name="SmartObjects">SmartObjects</Category>
  <Category CatID="9" Name="DependancyService">Dependency Service</Category>
  <Category CatID="10" Name="UserRoleManager">UserRoleManager Server</Category>
  <Category CatID="11" Name="CategoryServer">Category Server</Category>
  <Category CatID="12" Name="WorkflowServer">Workflow Server</Category>
  <Category CatID="13" Name="LiveCommServer">Live Comm Server</Category>
  <Category CatID="14" Name="EventBus">Event Bus</Category>
  <Category CatID="15" Name="EnvironmentServer">Environment Server</Category>
  <Category CatID="16" Name="SystemAudit">System Audit</Category>
  <Category CatID="17" Name="WorkActivity">Work Activity</Category>
  <Category CatID="18" Name="SmartObjectServices">SmartObject Services</Category>
  <Category CatID="19" Name="EventService">Event Service</Category>
  <Category CatID="22" Name="FormsManagementServer">Forms Management Server</Category>
  <Category CatID="21" Name="FormsClientServer">Forms Client Server</Category>
  <Category CatID="30" Name="DeploymentServer" name="DeploymentServer">Deployment Server</Category>
  <Category CatID="31" Name="PushNotificationService">PushNotification Service</Category>
  <Category CatID="37" Name="AuthorizationService">Authorization Service</Category>
  <Category CatID="60" Name="EnvironmentServices">Environment Services</Category>
  <Category CatID="61" Name="MessageBus">MessageBus</Category>
  <Category CatID="62" Name="SmartActions">SmartActions</Category>
  <Category CatID="63" Name="Extensibility">Server Extensibility</Category>
  <Category CatID="64" Name="IdentityService">Identity Service</Category>
  <Category CatID="65" Name="SecurityProvider">Security Provider</Category>
</CategoryList>

The actual text of the logged messages are also defined in the HostServerLogging.config file. See the code box below for an example.

Copy

Message definitions

<MessageList>
  <!-- Severity Levels Are: Ignore, Debug, Info, Warning, Error -->
  <!-- Custom Logging Targets per entry: ToFile="True" ToConsole="True" ToEventLog="False" ToCustom="False" -->
  <Message MsgID="0" Severity="Debug" Category="0" Name="Unknown" ToFile="True" ToConsole="True" ToEventLog="True" ToCustom="False">
    Unknown Event Occurred.
  </Message>
  <Message MsgID="1" Severity="Error" Category="0" Name="GeneralErrorMessage">
    {0}
  </Message>
  <Message MsgID="5" Severity="Warning" Category="0" Name="GeneralWarningMessage">
    {0}
  </Message>
  <Message MsgID="10" Severity="Info" Category="0" Name="GeneralInfoMessage">
    {0}
  </Message>
  <Message MsgID="15" Severity="Debug" Category="0" Name="GeneralDebugMessage">
    {0}
  </Message>
  <!-- System Info/Debug Messages -->
  <Message MsgID="1001" Severity="Info" Category="1" Name="ServerStarted">
    Host Server Started as {0}
  </Message>
  <Message MsgID="1002" Severity="Info" Category="1" Name="NETVersion">
    Using .NET Framework {0}
  </Message>
  <Message MsgID="1003" Severity="Info" Category="1" Name="HostServerVersion">
    Host Server Version: {0}
  </Message>
  . . .
</MessageList>

This is an example of a message in a log file. Note the MsgID of 1001 in the definition code and in the logged message:
Info 1001 Host Server Started as DENALLIX\K2service

Logging and Performance

As previously mentioned, each type of Host Server logging has its own performance implications. With stack trace disabled, and asynchronous queuing in use, only the log destination-type determines performance impacts. Informal tests have shown the performance quality to be (from best to worst):

  1. All Logging disabled
  2. Console (ConsoleExtension)
  3. SQL (ArchiveExtension)
  4. Event Logs (EventLogExtension)
  5. File (FileExtension)

Console logging offers no means of storing the logs past the buffer of the console window. Event Logs and SQL have similar performance; the distinguishing characteristic between them is ease of consumption. Event Logs tend to be difficult to traverse and can bog down heavily based on other OS-level conditions, whereas SQL is a much more flexible means of storage – offering much greater storage and filtering capacity. File logging is convenient for portability during troubleshooting, but has the highest overhead.

Considerations

  • The HostServerLogging.config file is case-sensitive. Active="True" is not the same as Active="true". The correct case is necessary or the K2 Host Server will not start.
  • Enable logging at the severity level necessary, and to the most efficient destination possible. Bear in mind that your performance impacts and needs should play a significant part in your logging decisions.
  • During setup, testing, and troubleshooting, increases the level of logging to Debug. This will allow you to see the maximum amount of information, and more easily determine exactly what is/isn’t working. Console and/or File logging are typically best suited to short-term monitoring that fits these use models.
  • During normal operations, scale back the severity of messages being logged, especially to the slower destinations. If needed, reserve File logging for only the most severe messages (Error). Use SQL logging for storing larger volumes of information, and/or for consolidating data from multiple K2 farm nodes.
  • Normal operating conditions should generally not need more than Warning level messages.
  • Only use Synchronous logging and stack trace inclusion under the supervision of K2 Support staff. You should not use these options under normal operating conditions.