Session Logs

By Y.P.Raju

Session logs contain information about the tasks that the Integration Service performs during a session, plus load summary and transformation statistics. By default, the Integration Service creates one session log for each session it runs. If a workflow contains multiple sessions, the Integration Service creates a separate session log for each session in the workflow. When you run a session on a grid, the Integration Service creates one session log for each DTM process.

In general, a session log contains the following information:

Allocation of heap memoryExecution of pre-session commandsCreation of SQL commands for reader and writer threadsStart and end times for target loadingErrors encountered during the session and general informationExecution of post-session commandsLoad summary of reader, writer, and DTM statisticsIntegration Service version and build number

Log Events Window

Use the Log Events window in the Workflow Monitor to view log events for a session. The Log Events window displays all log events for a session. Select a log event to view more information about the log event.

Session Log File Sample

A session log file provides most of the same information as the Log Events window for a session. The session log file does not include severity or DTM prepare messages.

The following sample shows a section of a session log file:

DIRECTOR> PETL_24044 The Master DTM will now connect and fetch the prepared session from the Preparer DTM.

DIRECTOR> PETL_24047 The Master DTM has successfully fetched the prepared session from the Preparer DTM.

DIRECTOR> DISP_20305 The [Master] DTM with process id [2968] is running on node [sapphire].

: (Mon Apr 03 16:19:47 2006)

DIRECTOR> TM_6721 Started [Connect to Repository].

DIRECTOR> TM_6722 Finished [Connect to Repository]. It took [0.656233] seconds.

DIRECTOR> TM_6794 Connected to repository [HR_80] in domain [StonesDomain] user [ellen]

DIRECTOR> TM_6014 Initializing session [s_PromoItems] at [Mon Apr 03 16:19:48 2006]

DIRECTOR> TM_6683 Repository Name: [HR_80]

DIRECTOR> TM_6684 Server Name: [Copper]

DIRECTOR> TM_6686 Folder: [Snaps]

DIRECTOR> TM_6685 Workflow: [wf_PromoItems]

DIRECTOR> TM_6101 Mapping name: m_PromoItems [version 1]

DIRECTOR> SDK_1805 Recovery cache will be deleted when running in normal mode.

DIRECTOR> SDK_1802 Session recovery cache initialization is complete.

The session log file includes the Integration Service version and build number.

DIRECTOR> TM_6703 Session [s_PromoItems] is run by 32-bit Integration Service [sapphire], version [8.1.0], build [0329].

Setting Tracing Levels

The amount of detail that logs contain depends on the tracing level that you set. You can configure tracing levels for each transformation or for the entire session. By default, the Integration Service uses tracing levels configured in the mapping.

Setting a tracing level for the session overrides the tracing levels configured for each transformation in the mapping. If you select a normal tracing level or higher, the Integration Service writes row errors into the session log, including the transformation in which the error occurred and complete row data. If you configure the session for row error logging, the Integration Service writes row errors to the error log instead of the session log. If you want the Integration Service to write dropped rows to the session log also, configure the session for verbose data tracing.

Set the tracing level on the Config Object tab in the session properties.

Table 25-3 describes the session log tracing levels:

Table 25-3. Session Log Tracing Levels

Tracing Level

Description

None Integration Service uses the tracing level set in the mapping.Terse Integration Service logs initialization information, error messages,

and notification of rejected data.Normal Integration Service logs initialization and status information, errors

encountered, and skipped rows due to transformation row errors. Summarizes session results, but not at the level of individual rows.

Verbose Initialization

In addition to normal tracing, the Integration Service logs additional initialization details, names of index and data files used, and detailed transformation statistics.

Verbose Data In addition to verbose initialization tracing, the Integration Service logs each row that passes into the mapping. Also notes where the Integration Service truncates string data to fit the precision of a column and provides detailed transformation statistics.When you configure the tracing level to verbose data, the Integration Service writes row data for all rows in a block when it processes a transformation.

You can also enter tracing levels for individual transformations in the mapping. When you enter a tracing level in the session properties, you override tracing levels configured for transformations in the mapping

Viewing Log Events

You can view the following types of log files:

Most recent session or workflow log. View the session or workflow log in the Log Events window for the last run workflow.Archived binary log files. View archived binary log files in the Log Events window.Archived text log files. View archived text log files in any text editor.

To view the Log Events window for a session or workflow:

1. In the Workflow Monitor, right-click the workflow or session.2. Select Get Session Log or Get Workflow Log.

To view an archived binary log file in the Log Events window:

1.

If you do not know the session or workflow log file name and location, check the Log File Name and Log File Directory attributes on the Session or Workflow Properties tab.

If you are running the Integration Service on UNIX and the binary log file is not accessible on the Windows machine where the PowerCenter client is running, you can transfer the binary log file to the Windows machine using FTP. 2. In the Workflow Monitor, click Tools > Import Log.3. Navigate to the session or workflow log file directory.4. Select the binary log file you want to view.5. Click Open.

To view a text log file:

1.

If you do not know the session or workflow log file name and location, check the Log File Name and Log File Directory attributes on the Session or Workflow Properties tab.

2. Navigate to the session or workflow log file directory.The session and workflow log file directory contains the text log files and the binary log files. If you archive log files, check the file date to find the latest log file for the session.

3. Open the log file in any text editor.

Working with the Session Log Interface Overview

By default, the Integration Service writes session events to binary log files on the node where the service process runs. In addition, the Integration Service can pass the session event information to an external library. In the external shared library, you can provide the procedure for how the Integration Service writes the log events.

PowerCenter provides access to the session event information through the Session Log Interface. When you create the shared library, you implement the functions provided in the Session Log Interface.

When the Integration Service writes the session events, it calls the functions specified in the Session Log Interface. The functions in the shared library you create must match the function signatures defined in the Session Log Interface.

Implementing the Session Log Interface

To configure the Integration Service to use a custom procedure for handling session event information, complete the following steps:

1. Create a shared library that implements the Session Log Interface.

2.

When you configure the Integration Service properties on the Administration Console, set the ExportSessionLogLibName property to the name of the shared library that you create.

The Integration Service and the Session Log Interface

When you set the ExportSessionLogLibName property of the Integration Service to the name of a shared library, the Integration Service performs the procedures defined in the shared library in addition to creating the event log files.

The Integration Service uses the shared library in the following manner:

1. The Integration Service loads the shared library and calls the INFA_InitSessionLog() function before it logs the first event in the session.

2.

Each time the Integration Service logs an event to the session log file, it calls the INFA_OutputSessionLog() function to pass the message, codes, and session information to the shared library.

3. When the session completes and the last event is logged, the Integration Service calls the INFA_EndSessionLog() and then unloads the shared library.

To ensure that the shared library can be correctly called by the Integration Service, follow the guidelines for writing the shared library.

Rules and Guidelines for Implementing the Session Log Interface

Use the following rules and guidelines when you write the code to implement the Session Log Interface:

You must implement all the functions in the Session Log Interface.

All calls from the Integration Service to the functions in the Session Log Interface are serialized except for abnormal termination. The Integration Service makes the calls to the functions as it logs events to the session log. Therefore, when you implement the functions in the Session Log Interface, you do not need to use mutex objects to ensure that only one thread executes a section of code at a time.When you implement the Session Log Interface in UNIX, do not perform any signal handling within the functions. This ensures that the functions do not interfere with the way that PowerCenter handles signals. Do not register or unregister any signal handlers.Since the Integration Service is a multi-threaded process, you must compile the shared library as a multi-threaded library so that it can be loaded correctly.

Functions in the Session Log Interface

The functions in the Session Log Interface do not return values. Therefore, a session cannot fail because of an Integration Service call to a function in the Session Log Interface.

Table 26-1 describes the functions in the Session Log Interface:

Table 26-1. Functions in the Session Log Interface

Function DescriptionINFA_InitSessionLog Provides information about the session for

which the Integration Service will write the event logs.

INFA_OutputSessionLogMsg Called each time an event is logged. Passes the information about the event.

INFA_OutputSessionLogFatalMsg Called when the last event is logged before an abnormal termination.

INFA_EndSessionLog Called after the last message is sent to the session log and the session terminates normally.

INFA_AbnormalSessionTerminationCalled after the last message is sent to the session log and the session terminates abnormally.

The functions described in this section use the time structures declared in the standard C header file time.h. The functions also assume the following declarations:

typedef int             INFA_INT32;typedef unsigned int    INFA_UINT32;typedef unsigned short  INFA_UNICHAR;typedef char            INFA_MBCSCHAR;typedef int             INFA_MBCS_CODEPAGE_ID;

INFA_InitSessionLog

void INFA_InitSessionLog(void ** dllContext,       const INFA_UNICHAR * sServerName,       const INFA_UNICHAR * sFolderName,

      const INFA_UNICHAR * sWorkflowName,       const INFA_UNICHAR * sessionHierName[]);

The Integration Service calls the INFA_InitSessionLog function before it writes any session log event. The parameters passed to this function provide information about the session for which the Integration Service will write the event logs.

INFA_InitSessionLog has the following parameters:

Parameter Data Type DescriptiondllContext Unspecified User-defined information specific to the shared

library. This parameter is passed to all functions in subsequent function calls. You can use this parameter to store information related to network connection or to allocate memory needed during the course of handling the session log output. The shared library must allocate and deallocate any memory associated with this parameter.

sServerName unsigned short

Name of the Integration Service running the session.

sFolderName unsigned short

Name of the folder that contains the session.

sWorkflowName unsigned short

Name of the workflow associated with the session

sessionHierName[]unsigned short array

Array that contains the session hierarchy. The array includes the repository, workflow, and worklet (if any) to which the session belongs. The size of the array divided by the size of the pointer equals the number of array elements.

INFA_OutputSessionLogMsg

void INFA_OutputSessionLogMsg(      void * dllContext,       time_t curTime,       INFA_UINT32 severity,       const INFA_UNICHAR * msgCategoryName,       INFA_UINT32 msgCode,       const INFA_UNICHAR * msg,       const INFA_UNICHAR * threadDescription);

The Integration Service calls this function each time it logs an event. The parameters passed to the function include the different elements of the log event message. You can use the parameters to customize the format for the log output or to filter out messages.

INFA_OutputSessionLogMsg has the following parameters:

Parameter Data Type DescriptiondllContext Unspecified User-defined information specific to the shared

library. You can use this parameter to store

information related to network connection or to allocate memory needed during the course of handling the session log output. The shared library must allocate and deallocate any memory associated with this parameter.

curTime time_t Time that the Integration Service logs the event.severity unsigned intCode that indicates the type of the log event

message. The event logs use the following severity codes:32: Debug Messages  8: Informational Messages  2: Error Messages

msgCategoryNameconstant unsigned short

Code prefix that indicates the category of the log event message.In the following example message, the string BLKR is the value passed in the msgCategoryName parameter.READER_1_1_1> BLKR_16003 Initialization completed successfully.

msgCode unsigned intNumber that identifies the log event message.In the following example message, the string 16003 is the value passed in the msgCode parameter.READER_1_1_1> BLKR_16003 Initialization completed successfully.

msg constantunsigned short

Text of the log event message. In the following example message, the string Initialization completed successfully is the value passed in the msg parameter.READER_1_1_1> BLKR_16003 Initialization completed successfully.

threadDescription constantunsigned short

Code that indicates which thread is generating the event log.In the following example message, the string READER_1_1_1 is the value passed in the threadDescription parameter.READER_1_1_1> BLKR_16003 Initialization completed successfully.

INFA_OutputSessionLogFatalMsg

void INFA_OutputSessionLogFatalMsg(void * dllContext, const char * msg);

The Integration Service calls this function to log the last event before an abnormal termination. The parameter msg is MBCS characters in the Integration Service code page.

When you implement this function in UNIX, make sure that you call only asynchronous signal safe functions from within this function.

INFA_OutputSessionLogFatalMsg has the following parameters:

Parameter Data Type Description

dllContext Unspecified User-defined information specific to the shared library. You can use this parameter to store information related to network connection or to allocate memory needed during the course of handling the session log output. The shared library must allocate and deallocate any memory associated with this parameter.

msg constant char

Text of the error message. Typically, these messages are assertion error messages or operating system error messages.

INFA_EndSessionLog

void INFA_EndSessionLog(void * dllContext);

The Integration Service calls this function after the last message is sent to the session log and the session terminates normally. You can use this function to perform clean up operations and release memory and resources.

INFA_EndSessionLog has the following parameter:

Parameter Data Type DescriptiondllContext UnspecifiedUser-defined information specific to the shared library.

You can use this parameter to store information related to network connection or to allocate memory needed during the course of handling the session log output. The shared library must allocate and deallocate any memory associated with this parameter.

INFA_AbnormalSessionTermination

void INFA_AbnormalSessionTermination(void * dllContext);

The Integration Service calls this function after the last message is sent to the session log and the session terminates abnormally. The Integration Service calls this function after it calls the INFA_OutputSessionLogFatalMsg function. If the Integration Service calls this function, then it does not call INFA_EndSessionLog.

For example, the Integration Service calls this function when the DTM aborts or times out. In UNIX, the Integration Service calls this function when a signal exception occurs.

Include only minimal functionality when you implement this function. In UNIX, make sure that you call only asynchronous signal safe functions from within this function.

INFA_AbnormalSessionTermination has the following parameter:

Parameter Data Type DescriptiondllContext UnspecifiedUser-defined information specific to the shared library.

You can use this parameter to store information related to network connection or to allocate memory needed during the course of handling the session log output. The shared

library must allocate and deallocate any memory associated with this parameter.

Session Log Interface Example

Informatica provides a sample program that uses the Session Log Interface. The sample program sends session log events to a text file called sesslog.log. You can view the sample program to gain more understanding about how to use the Session Log Interface to handle session log events based on your requirements. You can also compile the sample program and build an external library to send session log events to a text file.

The session log sample program is available when you install the PowerCenter SDK files from the Informatica Development Platform installer. By default, the session log sample program is installed in the following directory:

<SDKInstallationDir>/SessionLog_API/samples

Building the External Session Log Library

Use the make files provided with the sample program demo_sesslog.cpp to build the external library. The command to compile the library depends on the platform on which you build it.

Building the Library in UNIX

The following table shows the command to build the library on the different platforms:

Platform Compiler CommandSolaris CC make -f makefile_solHP-UX aCC make -f makefile_hpuxHP-UX 64 bit aCC make -f makefile_hpux64AIX xCl_r make -f makefile_aixAIX 64 bit xCl_r make -f makefile_aix64Linux g++ make -f makefile_linux

Building the Library in Windows

Use Microsoft Visual C++ 6.0 to build the sample session log library in Windows. Open the sample program demo_sesslog.dsw in Visual C++ 6.0 and build the project.

Using the External Session Log Library

After you build the library, you can use it to write the output of the session log into a file.

To use the sample external session log library, complete the following steps:

1. Log in to the Administration Console and select the Integration Service for which you want to set up the session log file.

2. On the Properties tab of the Integration Service, edit the configuration

properties.

3. Set the ExportSessionLogLibName property to the path and file name of the session log library you created from the session log sample program.