We're updating some of our product names. K2 Five will soon be Automation On-Prem. You may see both product names in our help pages while we make this change.

Custom logging extensions

K2 provides a number of standard logging targets which can output K2 log messages to a number of targets. These include:

K2 Host Server Console
Text File
Windows Event Log
SQL Database

These logging providers are configured by editing the file HostServerLogging.config, located by default in "%PROGRAMFILES%\K2\HostServer\Bin".

To learn more about logging in K2, please refer to the following topic in the Installation and Configuration Guide: K2 logging configuration.

In certain scenarios, it may be necessary to create custom logging extensions that will output the logging information from K2 to some other target, perhaps an enterprise-level system monitoring target or a Microsoft Operations Manager environment.

Logging can potentially output a great deal of information, especially if the log level is set to "all", so take care to write efficient and fast code. Although logging does occur asynchronously by default, given the amount of logging it is a good idea to keep your code optimized as much as possible.

Implementation

Create a new .NET Class project.
Add a reference to SourceCode.Logging.dll, located by default in "%PROGRAMFILES%\K2\HostServer\Bin" on the K2 application server.
Add using statements to import the SourceCode.Logging namespaces.
Implement a public class that inherits from BaseExtension.
If necessary, implement public properties and private accessors for any configuration settings needed by your logging extension. The properties will be populated by the values you set in the HostServerLogging configuration file, as long as the public property names exactly match the names used in the configuration settings.
Override and implement the LogMessage(MessageObject messageObject, string logStrMsg) method with your logging code.
Build and deploy your custom logging provider as described in the Deployment and Registration section below the code snippet.

// Add reference to SourceCode.Logging from "%PROGRAMFILES%\K2\HostServer\Bin"
using SourceCode.Logging;
using SourceCode.Logging.Extension;

namespace ExtendingTheK2Platform.K2_Server {
// Implement a public class that inherits from BaseExtension
public class CustomLogExtensions: BaseExtension {
  // If necessary, implement public properties and private accessors for any configuration settings needed by your logging extension.
  private string _configSetting1;
  private string _configSetting2;

  //These settings are included in the <Extension> entry for your custom logger
  //in the format: <Property Name= "Property" value= "Value" />
  public string ConfigSetting1 {
   get {
    return _configSetting1;
   }
   set {
    _configSetting1 = value;
   }
  }

  public string ConfigSetting2 {
   get {
    return _configSetting2;
   }
   set {
    _configSetting2 = value;
   }
  }

  protected override void LogMessage(MessageObject messageObject, string logStrMsg) {
   // TODO: write code to log your message here
   // you can check the message severity level with the MessageSeverity enum
   // levels which are: Debug, Info, Warning and Error
   // Note that the "LogLevel" configuration setting for your custom provider in the HostServerLogging.config file
   // affects which messages are passed into your logging provider build up a message using the properties
   // of the messageObject.
   StringBuilder sb = new StringBuilder();
   sb.Append(" Severity: ");
   sb.Append(messageObject.MessageSeverity.ToString());
   sb.Append(System.Environment.NewLine);
   sb.Append("Source: ");
   sb.Append(messageObject.MessageSource);
   sb.Append(System.Environment.NewLine);
   sb.Append("TimeStamp: ");
   sb.Append(messageObject.MessageTimestamp.ToString());
   sb.Append(System.Environment.NewLine);
   sb.Append("Message: ");
   sb.Append(messageObject.MessageString);
  }
}
}

Deployment and Registration

The custom logging provider .dll must be copied to the all the physical K2 application servers (in other words, the servers that run the K2 service) where the logging provider is used, and must be registered on each K2 application server by editing the HostServerLogging.config configuration file.

Stop the K2 service
Copy the output assembly to the following folder on all K2 Servers: "%PROGRAMFILES%\K2\HostServer\Bin"
Edit the file "%PROGRAMFILES%\K2\HostServer\Bin\HostServerLogging.config" and register the custom logging extension by adding an entry to the <Extensions> node. See a sample below; replace the values in square brackets with the appropriate values for your logging extension.
Enable the logging extension by adding an entry to the <LogLocationSettings> node. See a sample below, and replace the values in square brackets with the appropriate values for your logging extension. Also configure the LogLevel setting to whatever level of Logging messages you wish to output to your logging extension.
- "Name" must match the <Extension Name> value you used in step 3 above.
- "Active" enables or disables the logger.
- "LogLevel" determines the severity of the messages that will be forwarded to the logger. Available LogLevels are "All", "Debug", "Info", "Warning" and "Error".
Start the K2 service and test your logging provider.

<Extension Name="[SomeName]" type="[LoggerNamespace.LoggerClass]" location="%PROGRAMFILES%\K2\HostServer\Bin\[DLLName].dll">
<Property Name="[SomeProperty1]" value="[SomeValue1]"/>
<Property Name="[SomeProperty2]" value="[SomeValue2]"/>
</Extension>


<LogLocation Name="[SomeName]" Active="True" LogLevel="All" />

If you make any changes to the HostServerLogging.config file, you need to restart the K2 service to pick up the changes.

Debugging

You can debug custom logging extensions through remote debugging and attaching to the K2 server process. If you are debugging a remote K2 server, you will need to enable remote debugging. See http://msdn.microsoft.com/en-us/library/vstudio/y7f5zaaa.aspx for more information. If you are running a multi-K2 server environment (for example, when using NLB) we recommend that you shut down all but once of the K2 servers so that only one K2 server will run the logging extension.

Add breakpoints to your code
Copy the logging extension assembly and .pdb file to the K2 host server as described in the Deploying and Registration section
Modify the logging configuration file HostServerLogging.configand set the AsyncQueueEnabled value to False. <add key="AsyncQueueEnabled" value="False" />. This will ensure that your logging extensions is executed at the moment the event is encountered, rather than putting the event into an asynchronous log-processing queue.
Start the K2 service and then use Visual Studio's Debug > Attach to process option to attach to the K2HostServer.exe process. You may need to check the options Show Processes from all users and Show Processes in all sessions before the K2HostServer.exe process will show up.
When K2 encounters a logging event which is configured to be output to your custom logging extension, K2 Studio should launch and you can step through and debug your code.
When you are done debugging your logging extension, modify the logging configuration file HostServerLogging.configand set the AsyncQueueEnabled value to True to re-enable asynchronous logging, otherwise the performance of your K2 environment may be affected.

Attaching to the K2 host server process and hitting a breakpoint will suspend all execution on the K2 server, so use this approach carefully in any shared K2 environment. It is not recommended that you debug a production K2 server, unless downtime has been scheduled.