AquaLogic Interaction Development Kit (IDK) 6.0.0 |

# Plumtree.Remote.Logging Namespace

Provides a public interface which can send messages to the ALI Logging Toolkit.

See Logging Example for an annotated console application example, or refer to the more concise usage examples below.

## Recommendations for Configuration

When using the IDK in a web application context, we recommend configuring the logging framework via Web.config (Microsoft IIS). The web application configuration files shipped with the IDK contain annotated examples of how to configure logging.

When outside a web application context, we recommend declaring a single log management class within the project that will initialize the `LogFactory` (possibly as part of static initialization). This instance will provide instances of `ILogger` and possibly define a set of known component names for the application. This technique will help to avoid multiple initializations.

### Logging Application Name

This name is set during initialization of the `LogFactory` or configured in the web configuration file. The logging application name is used as a shared identifier which allows ALI log receivers to pick up messages from the logging application. All crawler, authentication, profile or search web services running in the same IDK web application instance will have the same logging application name.

### Component Name

All `ILogger` instances require a component name to identify the general context for a set of log messages. A component is a conceptual unit within an application. A small application may have only a single named component. It is reasonable to define component names as string constants that are localized in a log management class.

## Recommendations for Efficiency

The ALI logging framework is designed to suppress logging if there are no listening applications. For better performance, logging applications should use the `ILogger` interface to find out if there any listening applications before composing complex log messages. For example:

    if (logger.DebugEnabled) {
    	// compose a diagnostic message
    	logger.Debug( complex diagnostic message...);
    }

Similarly, the ALI logging framework will avoid internally composing formatted log messages when there are no listeners. For this reason, `ILogger` has numerous method overloads which allow passing a format string and various `Object` and numeric arguments. The arguments will only be processed and composed into a log message if there is an active listener for that log level. This helps avoid unnecessary string concatenation and makes for cleaner code.

Prefer this:

    	logger.Debug("An error occurred when {0} attempted to access {1} (context {2})",
                            user, resource, context);

to this:

    	logger.Debug(
    	    "An error occurred when " + user +
    	    " attempted to access " + resource +
    	    " (context " + context +
    	    ")");

## Usage Example

    using System;
    using Plumtree.Remote.Logging;
    namespace Plumtree.Remote.Logging.Test;
    {
      /// <summary>
      /// Provides an example of using the IDK
      ///  logging API.
      /// </summary>
      public class LoggingExampleLogUser
      {
        public LoggingExampleLogUser() : base()
        {
        }
        private static ILogger getLogger()
        {
          return LoggingExampleLogHolder.getLogger(typeof(LoggingExampleLogUser));
        }
        public static Object createObjectFor(String customerName)
        {
          ILogger logger = getLogger();
          logger.FunctionBegin("createObjectFor");
          Object retValue = new Object();
          logger.Info("Created new object for customer {0}.", customerName);
          if (logger.DebugEnabled())
          {
            logger.Debug("Details of new object: {0}, runtime type {1}, customer {2}",
             retValue.ToString(), retValue.GetType().FullName, customerName);
            }
          logger.FunctionEnd("createObjectFor");
          return retValue;
        }
        public static void Main(String[] arguments)
        {
          createObjectFor("Plumtree");
          for (int i = 0;i < arguments.Length;i++)
          {
            createObjectFor(arguments[i]);
          }
        }
      }
    }

    using System;
    using Plumtree.Remote.Logging;
    namespace Plumtree.Remote.Logging.Test;
    {
      public class LoggingExampleLogHolder
      {
        public LoggingExampleLogHolder() : base()
        {
        }
        private static bool logToNetworkWhenTrue = true;
        static LoggingExampleLogHolder()
        {
          LogFactory.Initialize("ExampleName", logToNetworkWhenTrue);
        }
        public static ILogger getLogger(Type loggingClass)
        {
          return LogFactory.GetLogger("LoggingExample", loggingClass);
        }
      }
    }

## Receiving and Viewing Log Messages

To receive and view log messages generated by the ALI logging framework, it is necessary to install the ALI Logging Toolkit and use one of its log receivers such as ALI Logging Spy or the ALI Logger. The receiver must be configured with a logging application name matching the sender. For more information, see the Configuring IDK Logging Options in the online developer documentation..

Namespace hierarchy

### Classes

Class | Description
--- | ---
LogFactory | The `LogFactory` is the starting point for the IDK Logging API, and offers static methods to configure logging, query configuration properties, and obtain `ILogger` instances.

### Interfaces

Interface | Description
--- | ---
ILogger | Defines the interface for logger instances, including logging methods and methods to test if various log levels are enabled. To create a logger object call `LogFactory.GetLogger()`. ### Logging Levels #### Severity-Based Logging Levels Debug - Provides a detailed descriptive message reporting a minor step taken in the code and/or providing variable values. Info - Reports a common operation that is of possible interest, for example, serving a new user request or making a remote procedure call. The IDK logging service sends an Info message to the "IDK" component when it is initialized. Warn - Indicates a possible problem which the person responsible for the application should be aware of. The IDK logging service sends a Warn message to the "IDK" component when it is initialized if verbose logging is enabled for logging instrumentation, since the network or application administrator should be aware of possible security implications of sending remote call parameters to a cleartext logging channel. Error - Indicates a definite problem which should to be corrected. The message should state and explain the problem and suggest how to fix it. Fatal - A problem so severe that the application cannot continue to function. The message should state the problem, explain why it is a problem, and suggest how to fix it. Examples might include inability to obtain necessary system or network resources. #### Supplemental Logging Levels Action - Describes that some significant action has been taken. Examples of action traces include the beginning or ending of a startup routine or the start or completion of a new user request. Severity of Action traces are usually considered between Info and Warn. Function - Used at the very beginning and end of methods to illustrate code paths and provide context for messages occurring between the beginning and ending function messages. Performance - Used to measure operations that may be costly in time. Typically a pair of begin and end performance calls will bracket a blocking call to an operation of interest such as a disk read or write, remote call, external process invocation, database query, or large sort operation. ### Logging Performance Considerations To minimize the performance cost of logging and avoid unnecessary work when constructing log messages, use an overload of one of the logging methods that inserts values into a format string. The overloads help reduce string concatenation. Also wrap any complex message construction in a conditional block to avoid doing the work if there are no listeners at that log level, following the example in the namespace summary.