pegasus/src/Pegasus/Common/Tracer.h - diff

Return to Tracer.h CVS log

Up to [Pegasus] / pegasus / src / Pegasus / Common

Diff for /pegasus/src/Pegasus/Common/Tracer.h between version 1.1.2.3 and 1.43

version 1.1.2.3, 2001/08/01 23:13:01

version 1.43, 2008/10/22 08:11:24

Line 1

//%/////////////////////////////////////////////////////////////////////////////

//%2006////////////////////////////////////////////////////////////////////////

// The Open Group, Tivoli Systems

// Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.

// IBM Corp.; EMC Corporation, The Open Group.

// IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.

// EMC Corporation; VERITAS Software Corporation; The Open Group.

// EMC Corporation; Symantec Corporation; The Open Group.

// Permission is hereby granted, free of charge, to any person obtaining a copy

// of this software and associated documentation files (the "Software"), to

Line 21

Line 29

//==============================================================================

// Author: Sushma Fernandes, Hewlett-Packard Company (sushma_fernandes@hp.com)

// Modified By:

//%/////////////////////////////////////////////////////////////////////////////

#ifndef Pegasus_Tracer_h

#define Pegasus_Tracer_h

#include <stdarg.h>

#include <cstdarg>

#include <fstream>

#include <Pegasus/Common/String.h>

#include <Pegasus/Common/System.h>

#include <Pegasus/Common/Logger.h>

#include <Pegasus/Common/TraceComponents.h>

#include <Pegasus/Common/InternalException.h>

#include <Pegasus/Common/TraceFileHandler.h>

#include <Pegasus/Common/TraceHandler.h>

#include <Pegasus/Common/Linkage.h>

#include <Pegasus/Common/SharedPtr.h>

PEGASUS_NAMESPACE_BEGIN

/** Tracer implements tracing of messages to a defined file

/**

Trace component identifiers. This list must be kept in sync with the

TRACE_COMPONENT_LIST in Tracer.cpp.

The tracer uses the _traceComponentMask 64bit field to mask

the user configured components.

Please ensure that no more than 64 Trace Component ID's are specified.

enum TraceComponentId

{

TRC_XML_PARSER,

TRC_XML_WRITER,

TRC_XML_READER,

TRC_XML_IO,

TRC_HTTP,

TRC_CIM_DATA,

TRC_REPOSITORY,

TRC_DISPATCHER,

TRC_OS_ABSTRACTION,

TRC_CONFIG,

TRC_IND_HANDLER,

TRC_AUTHENTICATION,

TRC_AUTHORIZATION,

TRC_USER_MANAGER,

TRC_REGISTRATION,

TRC_SHUTDOWN,

TRC_SERVER,

TRC_INDICATION_SERVICE,

TRC_INDICATION_SERVICE_INTERNAL,

TRC_MESSAGEQUEUESERVICE,

TRC_PROVIDERMANAGER,

TRC_OBJECTRESOLUTION,

TRC_WQL,

TRC_CQL,

TRC_THREAD,

TRC_IPC,

TRC_IND_HANDLE,

TRC_EXP_REQUEST_DISP,

TRC_SSL,

TRC_CONTROLPROVIDER,

TRC_CIMOM_HANDLE,

TRC_BINARY_MSG_HANDLER,

TRC_L10N,

TRC_EXPORT_CLIENT,

TRC_LISTENER,

TRC_DISCARDED_DATA,

TRC_PROVIDERAGENT,

TRC_IND_FORMATTER,

TRC_STATISTICAL_DATA,

TRC_CMPIPROVIDER,

TRC_INDICATION_GENERATION,

TRC_INDICATION_RECEIPT,

TRC_CMPIPROVIDERINTERFACE,

TRC_WSMSERVER,

TRC_LOGMSG

};

/** Token used for tracing functions.

struct TracerToken

{

TraceComponentId component;

const char* method;

};

/** Tracer implements tracing of messages to a defined file

class PEGASUS_COMMON_LINKAGE Tracer

{

public:

/** Trace facilities

File - tracing occurs to the trace file

Log - tracing occurs through the Pegasus Logger class

Keep the TRACE_FACILITY_LIST in sync with the TRACE_FACILITY_INDEX,

so that the index matches the according string in the list.

static char const* TRACE_FACILITY_LIST[];

enum TRACE_FACILITY_INDEX

{

TRACE_FACILITY_FILE = 0,

TRACE_FACILITY_LOG = 1,

TRACE_FACILITY_MEMORY = 2

};

/** Levels of trace

Trace messages are written to the trace file only if they are at or

above a given trace level

LEVEL1 - Function Entry/Exit

LEVEL1 - Severe and log messages

LEVEL2 - Basic flow trace messages, low data detail

LEVEL3 - Inter-function logic flow, medium data detail

LEVEL4 - High data detail

Line 61

Line 145

static const Uint32 LEVEL3;

static const Uint32 LEVEL4;

// PEGASUS_REMOVE_TRACE defines the compile time inclusion of the Trace

/** Traces the given character string.

// interfaces. If defined the interfaces map to empty functions

Overloaded to include the filename

and line number of trace origin.

@param fileName filename of the trace originator

@param lineNum line number of the trace originator

@param traceComponent component being traced

@param cstring the character string to be traced

static void traceCString(

const char* fileName,

const Uint32 lineNum,

const TraceComponentId traceComponent,

const char* cstring);

#ifdef PEGASUS_REMOVE_TRACE

/** Traces the message in the given CIMException object. The message

written to the trace file will include the source filename and

line number of the CIMException originator.

@param traceComponent component being traced

@param level trace level of the trace message

@param cimException the CIMException to be traced.

static void traceCIMException(

const TraceComponentId traceComponent,

const Uint32 level,

const CIMException& cimException);

inline static void trace(

/** Gets an HTTP request message.

const Uint32 traceComponent,

const Uint32 traceLevel,

const char *fmt,

...)

{

// empty function

}

inline static void trace(

Given an HTTP request message, this method checks if the

const char* fileName,

message contains a "Basic" authorization header.

const Uint32 lineNum,

const Uint32 traceComponent,

const Uint32 traceLevel,

const char* fmt,

...)

{

// empty function

}

#else

If true, the username/passwd is suppressed and returned.

Otherwise the request message is returned without any changes.

/** Traces the given message

@param requestMessage requestMessage to be checked

@param traceComponent component being traced

@param traceLevel trace level of the trace message

@param *fmt printf style format string

@param ... variable argument list

inline static void trace(

const Uint32 traceComponent,

const Uint32 traceLevel,

const char *fmt,

...)

{

va_list argList;

va_start(argList,fmt);

@return request message

_trace(traceComponent,traceLevel,fmt,argList);

va_end(argList);

}

/** Traces the given message. Overloaded to include the filename and

the line number of trace origin.

@param fileName filename of the trace originator

@param lineNum line number of the trace originator

@param traceComponent component being traced

@param traceLevel trace level of the trace message

@param *fmt printf style format string

@param ... variable argument list

inline static void trace(

static SharedArrayPtr<char> getHTTPRequestMessage(

const char* fileName,

const Buffer& requestMessage);

const Uint32 lineNum,

const Uint32 traceComponent,

const Uint32 traceLevel,

const char* fmt,

...)

{

va_list argList;

va_start(argList,fmt);

/** Set the trace file to the given file

_trace(fileName,lineNum,traceComponent,traceLevel,fmt,argList);

@param traceFile full path of the trace file

va_end(argList);

@return 0 if the filepath is valid

}

1 if the traceFile is an empty string or

if an error occurs while opening the file

in append mode

static Uint32 setTraceFile(const char* traceFile);

#endif

/** Set the trace level to the given level

@param level trace level to be set

@return 0 if trace level is valid

1 if trace level is invalid

static Uint32 setTraceLevel(const Uint32 level);

// End of PEGASUS_REMOVE_TRACE

/** Set components to be traced

@param traceComponents list of components to be traced,

components should be separated by ','

static void setTraceComponents(

const String& traceComponents);

/** Set trace facility to be used

@param traceFacility facility to be used for tracing,

for example Log or File.

@return 0 if trace facility is valid

1 if trace facility is invalid

static Uint32 setTraceFacility(const String& traceFacility);

/** Get trace facility currently in use

@return TRACE_FACILITY_FILE - if trace facility is file

TRACE_FACILITY_LOG - if trace facility is the log

TRACE_FACILITY_MEMORY - if trace facility is memory tracing

static Uint32 getTraceFacility();

/** Set buffer size to be used for the memory tracing facility

@param bufferSize buffer size in Kbyte to be used for memory tracing

@return true if function was successfully.

static Boolean setTraceMemoryBufferSize(Uint32 bufferSize);

/** Flushes the trace buffer to traceFilePath. This method will only

have an effect when traceFacility=Memory.

static void flushTrace();

/** Traces method entry.

@param token TracerToken

@param fileName filename of the trace originator

@param lineNum line number of the trace originator

@param traceComponent component being traced

@param methodName method being traced

inline static void traceEnter(

static void traceEnter(

const char* fileName,

TracerToken& token,

const Uint32 lineNum,

const char* file,

const Uint32 traceComponent,

size_t line,

const char* methodName)

TraceComponentId traceComponent,

{

const char* method);

_traceEnter( fileName, lineNum, traceComponent, "%s %s",

_FUNC_ENTER_MSG, methodName);

}

/** Traces method exit.

@param token TracerToken containing component and method

@param fileName filename of the trace originator

@param lineNum line number of the trace originator

@param traceComponent component being traced

@param methodName method being traced

inline static void traceExit(

static void traceExit(

const char* fileName,

TracerToken& token,

const Uint32 lineNum,

const char* file,

const Uint32 traceComponent,

size_t line);

const char* methodName)

{

_traceExit( fileName, lineNum, traceComponent, "%s %s",

_FUNC_EXIT_MSG, methodName);

}

/** Set the trace file to the given file

/** Validates the File Path for the trace File

@param traceFile full path of the trace file

@param filePath full path of the file

@return 0 if the filepath is valid

@return 1 if the file path is valid

1 if an error occurs while opening the file in

0 if the file path is invalid

append mode

static Uint32 setTraceFile(const char* traceFile);

static Boolean isValidFileName(const char* filePath);

/** Set the trace level to the given level

/** Validates the trace components

@param traceLevel trace level to be set

@param traceComponents comma separated list of trace components

@return 0 if trace level is valid

@return 1 if the components are valid

1 if trace level is invalid

0 if one or more components are invalid

static Uint32 setTraceLevel(const Uint32 traceLevel);

static Boolean isValidComponents(const String& traceComponents);

/** Set components to be traced

/** Validates the trace components

@param traceComponents list of components to be traced, components

@param traceComponents comma separated list of trace components

should be separated by ','

@param invalidComponents comma separated list of invalid components

@return 1 if the components are valid

0 if one or more components are invalid

static void setTraceComponents(String traceComponents);

static Boolean isValidComponents(

const String& traceComponents,

String& invalidComponents);

private:

/** Validates the trace facility string value

@param traceFacility The trace facility as string

@return 1 if the trace facility is valid

0 if the trace facility is invalid

static Boolean isValidTraceFacility( const String& traceFacility );

static const char _COMPONENT_SEPARATOR;

/** Signals the trace to be running OOP and provides the file name

static const Uint32 _NUM_COMPONENTS;

extension of the trace file. If non-empty, this

static const Uint32 _STRLEN_MAX_UNSIGNED_INT;

value is used as an extension to the name of the trace file.

Boolean* _traceComponentMask;

@param oopTraceFileExtension Trace file extension.

Uint32 _traceLevelMask;

TraceFileHandler* _traceHandler;

static void setOOPTraceFileExtension(const String& oopTraceFileExtension);

static Tracer* _tracerInstance;

// Message Strings for fucntion Entry and Exit

/**

static const char _FUNC_ENTER_MSG[];

static const char _FUNC_EXIT_MSG[];

static Boolean isTraceOn() { return _traceOn; }

// Message Strings for Logger

static const char _LOG_MSG1[];

static const char _LOG_MSG2[];

// Checks if trace is enabled for the given component and trace level

// @param traceComponent component being traced

// @param traceLevel level of the trace message

// @param level level of the trace message

// @return 0 if the component and level are not enabled

// 1 if the component and level are enabled

static Boolean _isTraceEnabled(

static Boolean isTraceEnabled(

const Uint32 traceComponent,

const TraceComponentId traceComponent,

const Uint32 traceLevel);

const Uint32 traceLevel)

{

return ((traceLevel & _traceLevelMask) &&

(_traceComponentMask & ((Uint64)1 << traceComponent)));

}

// Traces the given message

private:

// @param traceComponent component being traced

// @param traceLevel level of the trace message

/** A static single indicator if tracing is turned on allowing to

// @param *fmt printf style format string

determine the state of trace quickly without many instructions.

// @param argList variable argument list

Used to wrap the public static trace interface methods to avoid

static void _trace(

obsolete calls when tracing is turned off.

const Uint32 traceComponent,

const Uint32 traceLevel,

static Boolean _traceOn;

const char* fmt,

va_list argList);

/** Internal only Levels of trace

These cannot be used in any of the trace calls directly, but are set

by methods of the Tracer class for specific purposes, such as trace

Enter and traceExit.

LEVEL0 - Trace is switched off

LEVEL5 - used for method enter & exit

static const Uint32 LEVEL0;

static const Uint32 LEVEL5;

static const char _COMPONENT_SEPARATOR;

static const Uint32 _NUM_COMPONENTS;

static const Uint32 _STRLEN_MAX_UNSIGNED_INT;

static const Uint32 _STRLEN_MAX_PID_TID;

static Uint64 _traceComponentMask;

static Uint32 _traceLevelMask;

static Tracer* _tracerInstance;

Uint32 _traceMemoryBufferSize;

Uint32 _traceFacility;

Boolean _runningOOP;

TraceHandler* _traceHandler;

String _traceFile;

String _oopTraceFileExtension;

// Message Strings for function Entry and Exit

static const char _METHOD_ENTER_MSG[];

static const char _METHOD_EXIT_MSG[];

// Factory function to create an instance of the matching trace handler

// for the given type of traceFacility.

// @param traceFacility type of trace handler to create

void _setTraceHandler( Uint32 traceFacility );

// Validates if the given file path if it is eligible for writing traces.

// @param fileName a file intended to be used to write traces

static Boolean _isValidTraceFile(String fileName);

// Traces the given message. Overloaded to include the file name and the

// line number as one of the parameters.

// @param traceComponent component being traced

// @param traceLevel level of the trace message

// @param message message header (file name:line number)

// @param *fmt printf style format string

// @param argList variable argument list

static void _trace(

const char* fileName,

const Uint32 lineNum,

const Uint32 traceComponent,

const TraceComponentId traceComponent,

const Uint32 traceLevel,

const char* fmt,

va_list argList);

// Called by all the trace interfaces to log message to the

// Traces the message in the given CIMException object. The message

// trace file

// to be written to the trace file will include the source filename and

// @param fileName filename of the trace originator

// line number of the CIMException originator.

// @param lineNum line number of the trace originator

// @param traceComponent component being traced

// @param CIMException the CIMException to be traced.

static void _traceCIMException(

const TraceComponentId traceComponent,

const CIMException& cimException);

// Called by all the trace interfaces to log message

// consisting of a single character string to the trace file

// @param traceComponent component being traced

// @param cstring the string to be traced

static void _traceCString(

const TraceComponentId traceComponent,

const char* message,

const char* cstring);

// Called by all the trace interfaces to log message

// with variable number of arguments to the trace file

// @param traceComponent component being traced

// @param *fmt printf style format string

// @param argList variable argument list

static void _trace(

const Uint32 traceComponent,

const TraceComponentId traceComponent,

const char* message,

const char* fmt,

va_list argList);

// Traces method enter

// Traces method enter/exit

// @param fileName filename of the trace originator

// @param lineNum line number of the trace originator

// @param traceComponent component being traced

// @param *fmt printf style format string

// @param method name of the method

// @param ... variable argument list

static void _traceMethod(

static void _traceEnter(

const char* fileName,

const Uint32 lineNum,

const Uint32 traceComponent,

const TraceComponentId traceComponent,

const char* fmt,

const char* methodEntryExit,

...);

const char* method);

// Traces method exit

// @param fileName filename of the trace originator

// @param traceComponent component being traced

// @param *fmt printf style format string

// @param ... variable argument list

static void _traceExit(

const char* fileName,

const Uint32 lineNum,

const Uint32 traceComponent,

const char* fmt,

...);

// Tracer constructor

// Constructor is private to prevent construction of Tracer objects

Line 290

Line 428

// Returns the Singleton instance of the Tracer

// @return Tracer* Instance of Tracer

static Tracer* _getInstance();

friend class TraceCallFrame;

friend class TracePropertyOwner;

friend class TraceMemoryHandler;

friend class TraceFileHandler;

};

// Define the macros for method entry/exit

//==============================================================================

// PEGASUS_REMOVE_TRACE defines the compile time inclusion of the Trace

// interfaces. If defined the interfaces map to empty functions.

//==============================================================================

#ifdef PEGASUS_REMOVE_TRACE

#define PEG_FUNC_ENTER(traceComponent,methodName)

#define PEG_FUNC_EXIT(traceComponent,methodName)

inline void Tracer::traceCString(

const char* fileName,

const Uint32 lineNum,

const TraceComponentId traceComponent,

const char* cstring)

{

// empty function

}

inline void Tracer::traceCIMException(

const TraceComponentId traceComponent,

const Uint32 level,

const CIMException& cimException)

{

// empty function

}

static SharedArrayPtr<char> getHTTPRequestMessage(

const Buffer& requestMessage)

{

//empty function

return SharedArrayPtr<char>();

}

inline Uint32 Tracer::setTraceFile(const char* traceFile)

{

// empty function

return 0;

}

inline Uint32 Tracer::setTraceLevel(const Uint32 level)

{

// empty function

return 0;

}

inline void Tracer::setTraceComponents(const String& traceComponents)

{

// empty function

}

inline Uint32 Tracer::setTraceFacility(const String& traceFacility)

{

// empty function

return 0;

}

inline Uint32 Tracer::getTraceFacility()

{

// empty function

return 0;

}

inline Boolean Tracer::setTraceMemoryBufferSize(Uint32 bufferSize)

{

// empty function

return true;

}

inline void Tracer::flushTrace()

{

// empty function

return;

}

#endif /* PEGASUS_REMOVE_TRACE */

//==============================================================================

// Tracing macros

//==============================================================================

// Defines a variable that bypasses inclusion of line and filename in output.

// #define PEGASUS_NO_FILE_LINE_TRACE=1 to exclude file names and line numbers

#ifdef PEGASUS_NO_FILE_LINE_TRACE

# define PEGASUS_COMMA_FILE_LINE /* empty */

# define PEGASUS_FILE_LINE_COMMA /* empty */

#else

/** Macro for tracing method entry

# define PEGASUS_COMMA_FILE_LINE ,__FILE__,__LINE__

@param traceComponent component being traced

# define PEGASUS_FILE_LINE_COMMA __FILE__,__LINE__,

@param methodName name of the method

#endif

#define PEG_FUNC_ENTER(traceComponent,methodName) \

Tracer::traceEnter(__FILE__, __LINE__,traceComponent,methodName)

/** Macro for tracing method exit

#ifdef PEGASUS_REMOVE_TRACE

@param traceComponent component being traced

@param methodName name of the method

# define PEG_METHOD_ENTER(comp,meth)

# define PEG_METHOD_EXIT()

#define PEG_FUNC_EXIT(traceComponent,methodName) \

# define PEG_TRACE(VAR_ARGS)

Tracer::traceExit(__FILE__,__LINE__,traceComponent,methodName)

# define PEG_TRACE_CSTRING(comp,level,chars)

#else /* PEGASUS_REMOVE_TRACE */

// remover trace code for method enter/exit

# ifdef PEGASUS_REMOVE_METHODTRACE

# define PEG_METHOD_ENTER(comp,meth)

# define PEG_METHOD_EXIT()

# else

# define PEG_METHOD_ENTER(comp, meth) \

TracerToken __tracerToken; \

__tracerToken.method = 0; \

do \

{ \

if (Tracer::isTraceOn()) \

Tracer::traceEnter( \

__tracerToken PEGASUS_COMMA_FILE_LINE, comp, meth); \

} \

while (0)

# define PEG_METHOD_EXIT() \

do \

{ \

if (Tracer::isTraceOn()) \

Tracer::traceExit(__tracerToken PEGASUS_COMMA_FILE_LINE); \

} \

while (0)

#endif

// Macro to trace character lists. the do construct allows this to appear

// as a single statement.

# define PEG_TRACE_CSTRING(comp, level, chars) \

do \

{ \

if (Tracer::isTraceOn()) \

{ \

if (Tracer::isTraceEnabled(comp, level)) \

{ \

Tracer::traceCString(PEGASUS_FILE_LINE_COMMA comp, chars); \

} \

while (0)

// This class is constructed with the same arguments passed to PEG_TRACE().

// The constructor saves all the fixed arguments and calls va_start() on

// the varying arguments (wherein the va_list argument is the ap member of

// this class). The PEG_TRACE() macro eventually calls invoke() with the

// file and line macros in order to write the trace entry. For more details,

// see the comments below on the PEG_TRACE() macro.

class TraceCallFrame

{

public:

const char* file;

Uint32 line;

TraceCallFrame(const char* file_, Uint32 line_) : file(file_), line(line_)

{

}

PEGASUS_FORMAT(4, 5)

inline void invoke(

const TraceComponentId component,

const Uint32 level,

const char* format,

...)

{

if (Tracer::isTraceEnabled(component, level))

{

va_list ap;

va_start(ap, format);

Tracer::_trace(file, line, component, format, ap);

va_end(ap);

}

~TraceCallFrame()

{

}

};

// This macro is a wrapper for calling the printf-style form of the

// Tracer::trace() function. Since macros cannot have a varying number of

// arguments, PEG_TRACE() must be invoked with double parentheses. For

// example:

// PEG_TRACE((TRC_HTTP, Tracer::LEVEL1, "Oops: %d", 999));

// This macro offers two advantages over the calling trace() directly.

// 1. It eliminates the call to trace() if isTraceOn() returns false.

// This has proven to reduce the expense of servicing a request

// (when tracing is off) by as much as 3%.

// 2. It implicitly injects the __FILE__ and __LINE__ macros, relieving

// the caller of this burden.

# define PEG_TRACE(VAR_ARGS) \

do \

{ \

if (Tracer::isTraceOn()) \

{ \

TraceCallFrame frame(__FILE__, __LINE__); \

frame.invoke VAR_ARGS; \

} \

while (0)

#endif /* !PEGASUS_REMOVE_TRACE */

PEGASUS_NAMESPACE_END

#endif /* Pegasus_Tracer_h */

Legend:

Removed from v.1.1.2.3
changed lines
	Added in v.1.43

No CVS admin address has been configured