One of the first log files that is created in K2 blackpearl is the installation log file that is created during the installation process.

The K2 blackpearl installation log file allows you to troubleshoot installation issues. Occasionally a problem occurs with the K2 blackpearl setup, and you may have to use the installation log file as one of your tools to determine what the issue is.

During the installation and configuration of K2 blackpearl, a log file is created. Once the Configuration Manager has finished running, a link to the log file detailing the installation is available by clicking on this link surfaced through the Configuration Manager. The content of the installation log file is useful when diagnosing issues with the installation.

The log file is created by the Configuration Manager, and the installation log files can be found in the following location:

%PROGRAMFILES%K2 blackpearlConfigurationLog

The installation log file is called InstallReport.log, and an example of an installation log file is shown in Figure 19-1.

Figure 19.1. Figure 19-1

The installation log file contains details of the following:

In addition to all this information, a detailed list of the relevant dependencies for each component are logged in the Installation log file.

The Installation log file is an excellent resource to debug installation problems with the K2 Support Team and will show details about the original installation, any upgrades to the K2 blackpearl server, and any SharePoint installation.

Once your K2 blackpearl installation is up and running, the K2 blackpearl Logging Framework allows you to view details across the several server modules that provide different pieces of functionality in the K2 blackpearl Host Server.

The Logging Framework listens for messages of various severity levels from a range of classes and extensions that interact with it. These messages range from informational messages to error messages to debugging information to warning messages.

The Logging Framework, out-of-the-box, supports recording and displaying these messages in several different locations, including the K2 server console, the K2 server log file, the Event log, an archive extension, and MSMQ.

The Logging Framework is also built with the flexibility to select which loggers are active and the severity levels of each logger. With the flexibility of the Logging Framework, you can turn on or off any standard loggers or custom loggers and set different severity levels to suit the dynamic needs of any business.

K2 blackpearl ships with five different logging extensions. Each extension handles messages differently and should be sufficient for standard business needs. The logging extensions that are shipped with K2 blackpearl are listed in the following table:

Custom loggers can also be created and plugged into the Logging Framework. These logging extensions are controlled in the HostServerLogging.config file.

The K2 blackpearl Logging Framework contains its own XML-based configuration file, HostServerLogging.config. This consists of all the Logging Framework configuration settings as well as a list of message categories and specific predefined messages.

The HostServerLogging.config file can be found in the following location:

%PROGRAMFILES%K2 blackpearlHost ServerBin

The HostServerLogging.config file is a user-friendly and flexible configuration system, one that enables you to easily customize these configuration values postdeployment. Configuration data is stored in plain text files that are both readable and writable. Any standard text editor, XML parser, or scripting language can be used to interpret and update the configuration settings.

At run time, the HostServerLogging.config file is used to hierarchically compute a unique collection of configuration settings for each request. These configuration settings are calculated only once and then cached on the server. Any changes to the configuration file are detected and automatically applied to the affected applications. Hierarchical configuration settings are automatically calculated and cached again whenever a configuration file in the hierarchy is changed.

A typical HostServerLogging.config file looks as shown in Figure 19-2

Figure 19.2. Figure 19-2

The Logging Framework queues the messages in an internal "first in, first out" principle until the logging thread has been scheduled to obtain and process them.

Starting the Logging Framework forces the initialization of internal settings from the HostServerLogging.config file. The information in the HostServerLogging.config file settings section is stored as key/value pairs. The K2 blackpearl Logging Framework loads the values from the HostServerLogging.config file without the need to change the K2 blackpearl Logging Framework's source code.

The next sections discuss the composition of the HostServerLogging.config file.

<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="False" />
    <!-- Keep Log Files below this size. 0 = No Limit -->
    <add key="MaxFileSizeKB" value="0" />
    <!-- Keep Log Files below Timespan days:hours:minutes:seconds -->
    <add key="MaxFileTimeSpan" value="0:0:0:00" />
    <!-- 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>

<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" />
    </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.config"/>
          <Property Name="ConfigDBConnectionName"
                   value="HostserverDB"/>
    </Extension>
  </Extensions>

<ApplicationLevelLogSettings>
    <ApplicationLevelLogSetting Scope="Default">
      <LogLocationSettings>
        <LogLocation Name="ConsoleExtension" Active="True" LogLevel="Info" />
        <LogLocation Name="FileExtension" Active="False" LogLevel="All" />
        <LogLocation Name="EventLogExtension" Active="False" LogLevel="Debug" />
        <LogLocation Name="ArchiveExtension" Active="False" LogLevel="Debug" />
        <LogLocation Name="MSMQExtension" Active="False" LogLevel="Debug" />
      </LogLocationSettings>
    </ApplicationLevelLogSetting>
  </ApplicationLevelLogSettings>

<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="3" 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="DependencyService">
      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 Communication 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>
</CategoryList>

<Message Msg Severity="Debug" Category="16" Name="SQLInitSucceed" >
      Sql initialized (Svr:{0}, DB:{1})
</Message>

On the K2 blackpearl server, you can enable detailed logging options to help with troubleshooting and debugging. Changing the logging detail level can be useful when you are attempting to debug problems or if you just want to see what is happening on the K2 blackpearl server.

There are four distinct types of messages that can be surfaced through the Logging Framework. The severity levels of these messages are described in the following table:

To turn on the detailed logging, follow these steps:

After you have made your changes to HostServerLogging.config, save your changes. The K2 blackpearl Service will need to be restarted in order for this change to take effect and for the K2 blackpearl server to send logging information to the configured locations.

Depending on which logging location you have configured, you can see the detailed logging information by either running the K2 blackpearl server in Console mode, by viewing the K2 blackpearl Server log file, by viewing the Event log, by viewing the Archive, or by viewing the MSMQ.

You can also run the K2 blackpearl server in Console mode by using the K2 blackpearl shortcut (Start

To run the K2 server in Console mode follow these steps:

This will open the K2 blackpearl server in console mode (see Figure 19-4). Console mode is a useful troubleshooting tool, as all error and informational messages are sent to the console window, so you can watch what is going on. It is important that you run the service as the Service Account in order to accurately troubleshoot permissions and other errors.

Figure 19.4. Figure 19-4

When the File extension is turned on, messages are logged to the K2 blackpearl server log file. This log file is saved to the location specified in the properties of its Logging Framework configuration file.

If no path is specified, the K2 blackpearl server log file can be found in the following location:

%PROGRAMFILES%K2 blackpearlHost ServerBin

The name of the K2 blackpearl server log file is also taken from the Logging Framework configuration file, and if nothing is specified, the default value for the file is:

HostServerYYMMDD_x.log

The K2 blackpearl server log file looks like Figure 19-5.

Figure 19.5. Figure 19-5

The .csv (comma-separated value) file format is often used to exchange data between different applications. To view the K2 blackpearl server log file in a more usable format, you can save the log file with a .csv file extension, which when opened displays the file in a more accessible format in Excel.

To view the log file in Excel follow the following steps:

Filters can also be used to organize the information in various ways and to surface and sort the data that is most relevant to you.

When the Windows Event log extension is activated, the Logging Framework logs messages to the machine's Event log.

You can access the Event log in one of the following ways:

Under the Application node in the Event Viewer, you can sort for all messages of source SourceCode.Logging.Extension.EventLogExtension. See Figure 19-6.

Figure 19.6. Figure 19-6

When the Archive extension is activated, the Logging Framework logs messages to SQL Server. This allows queries to be run against logged messages.

By default, messages are logged to the HostServerDB connection. This can be modified to log messages to another location by changing the properties associated with this extension in the Logging Framework configuration file.

When you use the MSMQ extension, the Logging Framework logs messages to Microsoft Message Queuing. A logger can then be set up to monitor the Message Queue for messages and take action when necessary. This is useful when you are running multiple K2 blackpearl servers, in a server farm, for example, and one machine is set up to handle all of the logging.

The K2 blackpearl object model is broken down into a few high-level areas:

Under the Management assemblies that the K2 blackpearl platform provides, there are Supporting and Management assemblies. One of these assemblies is SourceCode.Logging.

SourceCode.Logging provides the classes for extending and logging to the K2 blackpearl Host Server log and delivering the output via different mechanisms, such as e-mail, text file, and the console.

The SourceCode.Logging assembly has the following namespaces:

If the five out-of-the-box logging extensions that come standard with K2 blackpearl do not meet your business needs, the Logging Framework makes it easy to create a class using the supporting and managing assemblies that plug into the architecture as a custom extension to fit different business needs.

When you are installing K2 blackpearl in a completely distributed environment where there are separate servers for the database server, K2 blackpearl server, application server, and SharePoint server, the "double-hop" authentication issue often arises.

The double-hop issue has to do with passing of credentials between, for example, a client, the Web server (first hop), and the database server (second hop) for authentication and access.

Often when you encounter the double-hop issue, you may see one of the following errors on the K2 blackpearl server:

NT AUTHORITYANONYMOUS LOGON
The request failed with HTTP status 401: Unauthorized.

When you encounter the double-hop issue, you need to use Kerberos. In a nutshell, Kerberos is a secure ticket-based protocol for authenticating a request. With delegation you simply allow another server/service to allow a Kerberos ticket to be created for another service on the originating user's behalf. This can be done at the computer level by using full delegation or with constrained delegation. Constrained delegation means that the Kerberos delegation can be executed only against a limited set of services.

The Service Principal Name (SPN) is a name that uniquely identifies an instance of a service to a client within Active Directory. SPNs cannot be duplicated in a given domain and must be specified for each name/alias that can be used to access the host.

Kerberos logging can be very helpful in diagnosing Kerberos authentication issues. Kerberos logging will display errors and notifications in the System Event log. It is a good idea to clear the Events in the System Event log so that new errors and warnings are easier to see.

To enable Kerberos logging on the Web server, perform these steps:

Another useful Kerberos troubleshooting tip is to output a log file for Kerberos. This can be done by adding the following two entries in the Registry:

The Kerberos log file is written to the following location:

%WINDOWS%System32lsass.log

Please be aware that you need to switch off log to file when opening the output file lsass.log because of file locking. You can do this by changing LogToFile from "1" to "0". From the preceding you can see that K2 blackpearl logging allows you to record information about process execution in K2 blackpearl. This information is typically used by workflow developers for debugging purposes, and additionally, depending on the type and detail of information contained in the logging information, by experienced system administrators or technical support personnel to diagnose common problems with K2 blackpearl.

Microsoft provides two interfaces for System Monitor, PerfMon, and a Microsoft Management Console (MMC) version called Performance Logs and Alerts.

Because of the fact that the MMC version does not allow real-time monitoring, you should only use the MMC Performance Logs and Alerts when you need just logs and alerts. PerfMon should be used when your aim is to collect live data. PerfMon does everything that the MMC version does.

Performance Logs and Alerts (see Figure 19-7) can be opened in the following way:

Figure 19.7. Figure 19-7

PerfMon (see Figure 19-8) can be opened in one of the following ways:

Figure 19.8. Figure 19-8

Once you launch PerfMon, you will get a graph with a trace that provides you with a graphical display of all system activities. You can use PerfMon to monitor the utilization of system resources and to collect and view real-time performance data in the form of counters for server resources such as processor and memory use.

PerfMon can be used to assist you with the planning of upgrades, the tracking of processes that need to be optimized, the monitoring results of tuning and configuration scenarios, and the understanding of a workload and its effect on resource usage to identify bottlenecks. Bottlenecks can occur on practically any element of the system and may be caused by a malfunctioning resource, the system not having enough resources, or a program that dominates a particular resource.

K2 blackpearl provides K2 blackpearl-specific counters to PerfMon which allow you to monitor the K2 blackpearl server.

In order to activate the newly added K2 blackpearl monitoring functionalities, right-click anywhere on the graph. Select the Add Counters option (shown in Figure 19-9).

Result: The Add Counters dialog box is displayed.

Figure 19.9. Figure 19-9

You can now add the counters you want to monitor to the Performance Monitor user interface, and K2 blackpearl adds some specific counters that are useful for quickly getting an overall impression of how healthy your system is and where the problems are, if they exist.

The idea here is to see the counters that will be at low or zero values when the K2 blackpearl system is healthy and at high values when something is overloaded. A "perfectly healthy" system would show all counters flat lined at zero. Perfection is however unattainable, so you'll probably never see all of these counters flat-lined at zero in real life.

K2 blackpearl provides you with a number of K2 blackpearl-specific counters to monitor various aspects of the system.

Adding Counters to the Performance Monitor User Interface

Once you've chosen the counters you want, you can add them to the Performance Monitor user interface as follows:

1. In the Add Counters dialog box, select K2 server from the Performance object drop-down list.

2. Select the relevant counters from the list (see Figure 19-10).

3. Click Add.

4. Click Close.

The performance of the selected counters will now be displayed in the main user interface.

Figure 19.10. Figure 19-10