Custom logging extensions

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

• 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 the product, please refer to the following topic in the Installation and Configuration Guide: Logging configuration.

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

Implementation

1. Create a new .NET Class project.
2. Add a reference to SourceCode.Logging.dll, located by default in "%PROGRAMFILES%\K2\HostServer\Bin" on the application server.
3. Add using statements to import the SourceCode.Logging namespaces.
   
4. Implement a public class that inherits from BaseExtension.
5. 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.
6. Override and implement the LogMessage(MessageObject messageObject, string logStrMsg) method with your logging code.
7. Build and deploy your custom logging provider as described in the Deployment and Registration section below the code snippet.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
using System.Text; 
// 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 application servers (in other words, the servers that run the Nintex K2 service) where the logging provider is used, and must be registered on each application server by editing the HostServerLogging.config configuration file.

1. Stop the K2 service
2. Copy the output assembly to the following folder on all Servers: "%PROGRAMFILES%\K2\HostServer\Bin"
3. 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.
4. 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".
5. Start the K2 service and test your logging provider.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<!--
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:
-->
<Extension Name="[SomeName]" type="[LoggerNamespace.LoggerClass]" location="%PROGRAMFILES%\K2\HostServer\Bin\[DLLName].dll">
  <Property Name="[SomeProperty1]" value="[SomeValue1]"/>
  <Property Name="[SomeProperty2]" value="[SomeValue2]"/>
</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.
-->
<LogLocation Name="[SomeName]" Active="True" LogLevel="All" />

Debugging

You can debug custom logging extensions through remote debugging and attaching to the server process. If you are debugging a remote 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-server environment (for example, when using NLB) we recommend that you shut down all but one of the servers so that only one server will run the logging extension.

1. Add breakpoints to your code
2. Copy the logging extension assembly and .pdb file to the host server as described in the Deploying and Registration section
3. 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.
4. 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.
5. When the product encounters a logging event which is configured to be output to your custom logging extension, Visual Studio should launch and you can step through and debug your code.
6. 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 environment may be affected.