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 memory

Execution of pre-session commands
Creation of SQL commands for reader and writer threads
Start and end times for target loading
Errors encountered during the session and general information
Execution of post-session commands
Load summary of reader, writer, and DTM statistics
Integration 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 Description
Level
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 In addition to normal tracing, the Integration Service logs additional
Initialization 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:

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
1.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:

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
1.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.

When you configure the Integration Service properties on the Administration
Console, set the ExportSessionLogLibName property to the name of the
2.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:

The Integration Service loads the shared library and calls the
1.INFA_InitSessionLog() function before it logs the first event in the session.
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
2.session information to the shared library.
When the session completes and the last event is logged, the Integration
3.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 Description
INFA_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_AbnormalSessionTermination Called 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 Description

dllContext 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 Name of the Integration Service running the
short session.
sFolderName unsigned Name of the folder that contains the session.
short
sWorkflowName unsigned Name of the workflow associated with the session
short
sessionHierName[] unsigned Array that contains the session hierarchy. The
short array 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 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.
curTime time_t Time that the Integration Service logs the event.
severity unsigned Code that indicates the type of the log event
int message. The event logs use the following
severity codes:
32: Debug Messages
8: Informational Messages
2: Error Messages
msgCategoryName constant Code prefix that indicates the category of the log
unsigned event message.
short 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 Number that identifies the log event message.
int 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 constant Text of the log event message.
unsigned In the following example message, the string
short Initialization completed successfully is the value
passed in the msg parameter.
READER_1_1_1> BLKR_16003 Initialization
completed successfully.
threadDescription constant Code that indicates which thread is generating the
unsigned event log.
short 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 Text of the error message. Typically, these messages are
char 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 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.

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 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.

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 Command

Solaris CC make -f makefile_sol
HP-UX aCC make -f makefile_hpux
HP-UX 64 bit aCC make -f makefile_hpux64
AIX xCl_r make -f makefile_aix
AIX 64 bit xCl_r make -f makefile_aix64
Linux 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:

Log in to the Administration Console and select the Integration Service for
1.which you want to set up the session log file.
On the Properties tab of the Integration Service, edit the configuration
2.properties.
Set the ExportSessionLogLibName property to the path and file name of the
3.session log library you created from the session log sample program.