Overview

Sponge's Logging Component is based on NLog - we built a centralized way of managing NLog configs in SharePoint that can be used with server- and client-side API.

  • Log Targets: The name of the target and it's NLog config.
  • Log Items: The name of your application with the associated Log Target.

Sponge Targets

  • Sponge File Target: very basic target that logs to a file.
  • Sponge Database Target: target that logs to the Sponge Logging Database. Check the Install page on how to install the Sponge Logging Database!
  • Sponge ULS Target: target that logs to the SharePoint ULS Log.

Usage

  • Go to the Sponge Administration Site --> Log Targets --> add any valid NLog config and it's name to the list.

alt text

  • Go to the Log Configs list and associate your application with a selected target. Note that the name of the app you specify here will be used in code to uniquely identify the log config.

alt text

That's it from the SharePoint side. Have a look at the server- and client-side API on how to get the configs from Sponge!

Online - Offline Mode

Sponge's logging component has different ways of loading the logging configuration.

  • Online: the config will be loaded from SharePoint which means that your application needs to have some kind of access (depending on server or client) to SP in order to work. The Online mode has to huge advantage that all configs are centralized in SharePoint and logging applications can be quickly associated with (different) targets. The downside is, that the loading of the config takes a little longer compared to offline mode. Also, when the target of your application is changed, the application needs to be restarted - iisreset, application pool recycle, restart - depending on the type of the application.

  • Offline: the offline mode works without SharePoint. That means you can use the NLog config just like you would on any other platform. But that does not mean you can't centralize your logging configs. The ClientLogManager provides a method to load a config from any given Path - that means you can store your configs on a Network Share and let your applications load the config from there.

Server Side

In order to use the server side API reference Sponge.dll and NLog.ddl lib and add using Sponge.Logging; to your usings.

Online
public void LogMsgServerSideOnline()
{
        //gets the log info from central admin
	var log = LogManager.GetOnline("Sponge Log Viewer");
	
        //gets the log info from site collection
        var log = LogManager.GetOnline("http://demo", "Sponge Log Viewer");

	//this will log a test message to the target that was associated with 'Sponge Log Viewer' in SP
	log.Debug("This is {0} debug msg", "my");
}
Offline
public void LogMsgServerSideOffline()
{
	//path to the config file; this can be local or a network share
	var path = "../../log.config";
	
	var name = "My Logger";
	
	//this will initalize the logger with name 'My Logger'
	//if you do not specify name it will use the default name 'Sponge.Logging.Logger'
	var log = LogManager.GetOffline(path, name);

	log.Debug("This is {0} debug msg", "my");
}

Client Side

In order to use the server side API reference Sponge.Client.dll and NLog.ddl from lib and add using Sponge.Client.Logging; to your usings.

Online
public void LogMsgClientSideOnline()
{
        //url to the Site Collection
        var spongeUrl = "http://demo";

        //name of the app in sharepoint
        var app = "Sponge Log Viewer";

        //whether the ClientLogManager should retrieve the log config from central admin (true) or from the relative Sponge Admin Page (false)
        //relative means --> "http://demo/Sponge" --> Sponge Logging & Configuration Component Feature has to be enabled in this Site Collection
        var central = false;

        //create the logger instance
	var log = ClientLogManager.GetOnline(spongeUrl, app, central);
	
	//this will log a test message to the target that was associated with 'Sponge Log Viewer' in SP
	log.Debug("This is {0} debug msg", "my");
}
Offline
public void LogMsgClientSideOffline()
{
	//path to the config file; this can be local or a network share
	var path = "../../log.config";
	
	var name = "My Logger";
	
	//this will initalize the logger with name 'My Logger'
	//if you do not specify name it will use the default name 'Sponge.Logging.Logger'
	var log = ClientLogManager.GetOffline(path, name);

	log.Debug("This is {0} debug msg", "my");
}
JavaScript

The Sponge JavaScript API allows you to use the logging component of Sponge in JavaScript. If you want to use the js API in a page where the Sponge Logging & Configuration Component Feature is not enabled (it will automatically inject sponge.js in every page), simply reference the _layouts/Sponge/scripts/sponge.js file.

The js API also supports Central & Relative installation, just like the rest of the API does.

Note: To make the js API work, you have to configure the Sponge Logging Web Service application in your (central/relative) admin site. It is automatically added on installation and will log to the ULS log. If that is fine with you, leave it like this, otherwise configure a different target. However, do not delete this application, otherwise the js api will fail.

try {
alllert("will fail");
}
catch(err) {
    //makes the call to the central admin installation
    sponge.logging.log("Error", err.message);

    //makes the call to the site collection http://demo
    sponge.logging.log("Error", err.message, "http://demo");
}

Supported API

Server Side

  • GetOnline(string loggerName): This initializes the logger with the configuration from Sponge Central Admin.

  • GetOnline(string siteCollUrl, string loggerName): This initializes the logger with the configuration from the specified siteCollectionUrl. NoteSponge Logging & Configuration Component Feature has to be enabled in this Site Collection.

  • GetOffline(): This initializes the logger with the local configuration from app.config and Name = "Sponge.Logging.Logger".

  • GetOffline(string configPath): This initializes the logger with the configuration from the config file at the given configPath and default name.

  • GetOffline(string configPath, string loggerName): This initializes the logger with the configuration from the config file at the given configPath and the given loggerName.

  • GetOffline(string configPath, Type loggerType): This initializes the logger with the configuration from the config file at the given configPath and the given loggerType.

Client Side

  • GetOnline(string siteCollUrl, string loggerName, bool central): This initializes the logger with the configuration from either Sponge Central Admin (central = true) or from siteCollUrl's Sponge Admin (central = false) Site. Note:Sponge Logging & Configuration Component Feature has to be enabled in this Site Collection.

  • GetOffline(): This initializes the logger with the local configuration from app.config and Name = "Sponge.Logging.Logger".

  • GetOffline(string configPath): This initializes the logger with the configuration from the config file at the given configPath and default name.

  • GetOffline(string configPath, string loggerName): This initializes the logger with the configuration from the config file at the given configPath and the given loggerName.

  • GetOffline(string configPath, Type loggerType): This initializes the logger with the configuration from the config file at the given configPath and the given loggerType.

Last edited Aug 9, 2013 at 6:00 AM by int32at, version 2

Comments

No comments yet.