Log Service Installation Instructions

(1)

TECHNICAL NOTE

Log Service Installation Instructions

Product version: 4.60

Document version: 1.1

Document creation date: 06-04-2006

Purpose

The purpose of the Log Service is to centrally handle log messages in one place for the entire Web site. This document describes how to install the Log Service and includes information on how to troubleshoot the Log Service.

(2)

2 | Log Service Installation Instructions

Revision Information

Document version Comments

1.0 4.60 release version.

1.1 Added the "Installing the Log Service on a Web Farm" chapter and infomation on how to start up the log service in DEBUG mode.

Introduction

From EPiServer 4.50, the Log Service is a part of the base installation. The purpose of the Log Service is to centrally handle log messages in one place for the entire Web site.

There are three logical parts in the Log Service

• Web server or an application that generates the log messages • Log Service to collect the log messages

• Analyzers to handle and present the log messages.

Installation Prerequisites

System Requirements

For the full installation with the base example analyzers, the Log Service has the same requirements as EPiServer. Refer to the document "EPiServer Installation Instructions" for further information.

(3)

EPiServer Modules

Log Service also requires:

• EPiServer 4.50 or later. This is needed to present the analyzer values. • EPiServer Manager. This is used for a quick and easy installation.

Installing Log Service

Log Service can be installed in one of two ways, either with EPiServer Manager or manually. Instructions for how to install in both ways are described in this chapter.

Installation with EPiServer Manager

Follow the instructions below to install the Log Service with EPiServer Manager.

1. Select the Capabilities node under the Web site for which you want to generate log messages. 2. In the Logging/Statistics group box, click Enable.

Note The historical data saved in the database is based upon the web.config value EPsSiteName. If this

value is changed, historic information cannot be presented on the Web site. (Refer to the technical note "web.config Settings" for further information about the settings in web.config.)

Configure the Log Service to Use a Database

To configure the Log Service with a database, the connection string in the configuration file

(%programFiles%/EPiServer.LogService/EPiServer.LogService.exe.config) must be changed. Change the value for the parameter connectionString to a connection string to an EPiServer database.

SQL Server

<episerver.baseLibrary> <objectStores>

(4)

<add

type="EPiServer.Implementation.SqlObjectStore, EPiServer.Implementation" id="defaul t">

<parameter name="connectionString" value="Data Source=(local);Database=dbEPi ServerDemo450RC3;User Id=usrEPiServerDemo450RC3;Password=password;Network Library=D BMSSOCN;" /> Oracle <configuration> <episerver.baseLibrary> <objectStores> <add

type="EPiServer.Implementation.OracleObjectStore, EPiServer.Implementation" id="def ault">

<parameter

name="connectionString" value="Data Source=<TNS name>;User Id=<user>;Password=<pass word>" />

Manual Installation

If an older installation of the Log Service exists, uninstall this service according to the "Removing Log Service" chapter.

Follow the instructions below to install the Log Service manually.

1. Run the program installUtil.exe located in the .NET framework current version directory,

e.g. "c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\InstallUtil.exe" with the Log Service binary as argument.

c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\InstallUtil.exe c:\inetpub\wwwro ot\bin\EPiServer.LogService.exe

2. Rename the default configuration file named EPiServer.LogService.exe.config.default (located in the installation directory under %programFiles%) to EPiServer.LogService.exe.config.

3. Configure the LogService database, see Configure the Log Service to Use a Database 4. Start the service at the command prompt with the command

net start EPiServer.LogService.

5. Enable statisics logging for the Web site by renaming/copying EPiServerLog.config.Default to EPiServerLog.config from an EPiServer sample site Web root.

Advanced

Logging in EPiServer is based on the log4net product and must have the following properties: • One appender with the following values

- type="EPiServer.Diagnostics.EPiServerUdpAppender, EPiServer" - remoteAddress=<IP address to the log service>

- remotePort=<port defined for the log service, must be the same value as the udpClientPort property in the log service configuration file>

- encoding=Unicode (automatically added by the EPiServerUDPAppender) - a layout that generates log messages on the form %d\t<siteid>\t%m

• One logger on DEBUG level for the class EPiServer.DataAccess.PageSaveDB – to generate messages when a page is published.

(5)

Install Log Generator on an Existing Web Site

A component that generates a log message with a transparent .gif file for a Web page is available. The component generates a JavaScript, which in turn generates the path to the .gif file that generates the log message to the Log Service.

<EPiServer:LogGenerator runat="server" ID="PixelImg" />

In the sample project this component is implemented in the default framework, located in the file Templates\FrameWork\DefaultFrameWork.ascx

Installing the Log Service on a Web Farm

Only one log service is configured for all Web servers on a Web farm. For the sample analyzers, each Web server sends log messages to the log service over UDP and the log service publishes its results on a TCP/SOAP Web service that can be connected for all Web servers.

Architecture

Several Web servers can connect to one log service, but in normal case it is not recommended to use several log services to handle the messages.

Web server 1 Web server 2

TCP/SOAP UDP UDP

Log service

1. The Web servers are configured to send log messages to the log service in the EPiServerLog.config file located in the Web root for every Web server.

Example for sending log messages to a remote log service:

</appender>

2. The example analyzers are configured to publish their information on a TCP/SOAP Web service. To publish this to a remote host, add the via attribute to the configuration in

EPiServer.LogService.exe.config located in your EPiServer.LogService directory (normally %programFiles%\EPiServer.LogService)

(6)

Example configuration to publish the sample analyzer Time Span Analyzer over TCP/SOAP remote: <view type="EPiServer.Log.Analyzer.TimeSpanAnalyzerView, EPiServer.Log.Analyz ers"

protocol="TCP/SOAP"

endpoint="soap.tcp://localhost/TimeSpanAnalyzerView" via="soap.tcp://logservice.my.se/TimeSpanAnalyzerView "/>

3. Change the SOAP proxy so that it connects to the remote server. In the example code before EPiServer 4.60, this is implemented as a web.config setting EPsLogServiceHost. In your own analyzers you must change it yourself by adding a via attribute to the endpoint.

Example to add a via attribute to the time span analyzer's endpoint:

TimeSpanAnalyzerView client =new TimeSpanAnalyzerView();

Uri address = new Uri("soap.tcp://localhost/TimeSpanAnalyzerView"); Uri via = new Uri("soap.tcp://" + EPiServer.Global.EPConfig["EPsLogService Host"] + "/TimeSpanAnalyzerView");

client.Destination = new Microsoft.Web.Services2.Addressing.EndpointRefere nce(address, via);

Removing Log Service

Follow the instructions below to remove the Log Service.

1. Stop the service at the command prompt with the command

net stop EPiServer.LogService.

2. Run the program installUtil.exe located in the .NET framework current version directory (e.g.

c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\InstallUtil.exe ) with the arguments /u for uninstall and the binary for the Log Service

%EPiServer installation%\bin\EPiServer.LogService.exe E.g.:

c:\WINDOWS\Microsoft.NET\Framework\v1.1.4322\InstallUtil.exe /u c:\inetpub\ww wroot\bin\EPiServer.LogService.exe

3. Remove the directory %ProgramFiles%\EPiServer.LogService.

4. Remove the configuration file for logging on the Web server EPiServerLog.Config, which exists in the Web server root directory.

Advanced:

• To remove all logging sent to the Log Service, remove the appender that sends UDP messages (default is EPiServerUDPAppender).

• To remove the logging for published pages, remove the logger for the class EPiServer.DataAccess.PageSaveDB.

• To remove the logging for statistics, remove the logger for the class EPiServer.Util.PixelImg.

Log Service Troubleshooting

The first page of the sample site reads “The log service could not be connected.”

or

The Statistics tab in Edit mode reads “Cannot connect to the log service.”

(7)

Solution: Verify that the Log Service is started according to the "Validate that the Log Service is Functional"

chapter.

The statistical values are not changing.

Cause: No log messages are generated/come over the UDP channel. Solution: See the "Check the Log Configuration on the Web Server" chapter.

The Statistics tab in Edit mode reads “The log service is not configured with a database. Saved history will not be shown.”

Cause: The Log Service is not able to save data into the database. Solution: See the "Check if the Log Service is Configured" chapter.

Solutions

Check if the Log Service is Installed

The installation directory (%Program files%/EPiServer.LogService) should contain the executables and the configuration files for the Log Service. If it is empty, install the service according to the "Manual Installation" chapter.

Check the Log Configuration on the Web Server

Verify that the configuration file EPiServer.Config exists in the Web server's root directory. In the sample project the file is named EPiServerLog.Config.Default so it not will start logging automatically.

The configuration file must contain

• A UDPappender whose remoteAdress property is the Log Service IP address. remotePort must be set to the same value as the Log Service configuration property udpClientPort and encoding must be set to Unicode.

• A logger called EPiServer.DataAccess.PageSaveDB on DEBUG level, if the component for showing last published pages is to be used.

• A logger called EPiServer.Util.PixelImg on INFO level, if you want statistics generation with transparent gif to work

• A root logger, if you want a centralized logging for the whole Web site.

Check if the Log Service is Configured

The configuration file for the Log Service must be called EPiServer.LogService.exe.config and be located in the Log Service home directory (%Program files%\EPiServer.LogService.exe.config).

The Log Service is, by default, not started automatically when EPiServer is installed the file is called EPiServer.LogService.exe.config.Default.

Important configuration for the Log Service:

UDP port for log messages

udpClientPort has to be the same value as the Web service log configuration remotePort for the UDPappender located in the file EPiServer.Log.Config.

(8)

Check if the Logging is Done with Transparent GIF

If there is a reference to the transparent .gif file, there must also be a HTML tag on the page to be included in the statistics. This page should start with:

<img width='1' height='1' alt=''...

This tag generates a transparent .gif file that sends log messages to the Log Service if it is present on the Web site.

The log message that is sent by the transparent .gif has the following looks like this: 2005-04-12 10:52:05,444 |mySite|Page|...

Log4net will not write to the log file if EPiServerLog.Config is corrupt. Test if the configuration is correct by creating a file appender that writes log messages directly to a file and changes the log level for the root logger to DEBUG. If no file is created, the EPiServerLog.Config is corrupt and has to be rewritten.

Validate that the Log Service is Functional

In the installation directory for the Log Service, the log server's own log file is located in %Program files%\Logs\. If this file is not present, the initial error message is written to the Windows Event Handler on the local machine. The Log Service log should look like below if the Log Service is started.

Starting Udp Server, listen to port 7070

Start up the Log Service in DEBUG Mode

1. Open a command prompt and navigate to the root directory of the log service, normally %PROGRAMFILES%\EPiServer.LogService\

2. Shout down the normal log service by entering the following command net stop EPiServer.LogService

3. Start up EPiServer.LogService in DEBUG mode by entering the following command EPiServer.LogService DEBUG

4. This start ups the log service and outputs debug messages to the console in DEBUG mode. 5. To quit the log service, press ‘q’ followed by ENTER.

Copyright © ElektroPost Stockholm AB. ElektroPost and EPiServer® are registered trademarks of ElektroPost Stockholm AB. Other product and company names mentioned in this document may be the trademarks of their respective owners.

The document may be freely distributed in its entirety, either digitally or in printed format, to all EPiServer users. Changes to the content or partial copying of the content may not be carried out without permission from ElektroPost Stockholm AB:

ElektroPost Stockholm AB Finlandsgatan 38

SE-164 74 Kista Sweden

Changes are periodically made to the document and these will be published in new editions of the document. ElektroPost reserves the right to improve or change the products or programs included in this document at any time.

Log Service Installation Instructions

TECHNICAL NOTE