Class to encapsulate tracing functions. More...

#include <object.h>

Classes
class	Block
	Class to trace Execution blocks. More...

struct	Throttle
	Template class to reduce noise level for some logging. More...

class	ThrottleBase
	Class to reduce noise level for some logging. More...

Public Types
enum	Options { Blocks = 0x0001, DateAndTime = 0x0002, Timestamp = 0x0004, Thread = 0x0008, TraceLevel = 0x0010, FileAndLine = 0x0020, ThreadAddress = 0x0040, AppendToFile = 0x0080, GMTTime = 0x0100, RotateDaily = 0x0200, RotateHourly = 0x0400, RotateMinutely = 0x0800, RotateLogMask = RotateDaily + RotateHourly + RotateMinutely, ObjectInstance = 0x1000, ContextIdentifier = 0x2000, SingleLine = 0x4000, SystemLogStream = 0x8000, HasFilePermissions = 0x8000000, FilePermissionMask = 0x7ff0000, FilePermissionShift = 16 }
	Options for trace output. More...

Static Public Member Functions
static void	Initialise (const PArgList &args, unsigned options=Timestamp\|Thread\|Blocks, const char traceCount=PTRACE_ARG_TRACE, const char outputFile=PTRACE_ARG_OUTPUT, const char traceOpts=PTRACE_ARG_OPTION, const char traceRollover=PTRACE_ARG_ROLLOVER, const char *traceLevel=PTRACE_ARG_LEVEL)
	Set the most common trace options. More...

static void	Initialise (unsigned level, const char filename=NULL, unsigned options=Timestamp\|Thread\|Blocks, const char rolloverPattern=NULL)
	Set the most common trace options. More...

static void	Initialise (unsigned level, const char filename, const char rolloverPattern, unsigned options=Timestamp\|Thread\|Blocks)

static void	SetFilename (const char *filename)
	Set the trace output file. More...

static const char *	GetFilename ()
	Get the current filename for trace output. More...

static void	SetMaxLength (PINDEX length)
	Set the mmaximum length for logs. More...

static PINDEX	GetMaxLength ()
	Get the mmaximum length for logs. More...

static void	SetOptionsByName (const char *options)
	Set the trace options by name. More...

static std::string	GetOptionsByName ()
	Get current trace options by name. More...

static void	SetOptions (unsigned options)
	Set the trace options. More...

static void	ClearOptions (unsigned options)
	Clear the trace options. More...

static unsigned	GetOptions ()
	Get the current trace options. More...

static void	SetLevel (unsigned level)
	Set the trace level. More...

static unsigned	GetLevel ()
	Get the trace level. More...

static PBoolean	CanTrace (unsigned level)
	Determine if the level may cause trace output. More...

static void	SetStream (ostream *out)
	Set the stream to be used for trace output. More...

static ostream *	GetStream ()
	Get the stream being used for trace output. More...

static int	GetTimeZone ()
	Get the time zone being used for logging. More...

static ostream &	PrintInfo (ostream &strm, bool crlf=true)
	Output trace parameters (level, output, options etc) to stream. More...

static ostream &	Begin (unsigned level, const char fileName, int lineNum, const PObject instance=NULL, const char *module=NULL)
	Begin a trace output. More...

static ostream &	Begin (unsigned level, const char fileName, int lineNum, const char module, const PObject instance, const char defModule)

static ostream &	Begin (unsigned level, const char fileName, int lineNum, const PObject instance, const PObject defInstance, const char module)

static ostream &	End (ostream &strm)
	End a trace output. More...

static bool	CanTrace (const ThrottleBase &throttle)

static void	WalkStack (ostream &strm, PThreadIdentifier id=PNullThreadIdentifier, PUniqueThreadIdentifier uid=0, bool noSymbols=false)

static unsigned	GetNextContextIdentifier ()

Static Public Attributes
static unsigned	MaxStackWalk

Detailed Description

Class to encapsulate tracing functions.

This class does not require any instances and is only being used as a method of grouping functions together in a name space.

There are a number of macros for supporting tracing. These will all evaluate as empty in a "No Trace" build of the system:

Member Enumeration Documentation

enum PTrace::Options

Options for trace output.

Enumerator
Blocks	Include PTrace::Block constructs in output If this is bit is clear, all PTrace::Block output is inhibited regardless of the trace level. If set, the PTrace::Block may occur provided the trace level is greater than zero.
DateAndTime	Include date and time in all output.
Timestamp	Include (millisecond) timestamp in all output.
Thread	Include identifier for thread trace is made from in all output.
TraceLevel	Include trace level, as a numeric value, in all output.
FileAndLine	Include the file and line for the trace call in all output.
ThreadAddress	Include thread object pointer address in all trace output.
AppendToFile	Append to log file rather than resetting every time.
GMTTime	Output timestamps in GMT time rather than local time.
RotateDaily	If set, log file will be rotated daily.
RotateHourly	If set, log file will be rotated hourly.
RotateMinutely	If set, log file will be rotated every minute.
RotateLogMask	Mask for all the rotate bits.
ObjectInstance	Include object instance in all trace output.
ContextIdentifier	Include context identifier in all trace output.
SingleLine	Assure trace output is always on a single line.
SystemLogStream	SystemLog flag for tracing within a PServiceProcess application. Setting this flag will automatically execute `#SetStream(new PSystemLog)`.
HasFilePermissions	Flag indicating file permissions are to be set.
FilePermissionMask	Mask for setting standard file permission mask as used in open() or creat() system function calls.
FilePermissionShift

Member Function Documentation

static ostream& PTrace::Begin	(	unsigned	level,
		const char *	fileName,
		int	lineNum,
		const PObject *	instance = `NULL`,
		const char *	module = `NULL`
	)

static

Begin a trace output.

If the trace stream output is used outside of the provided macros, it should be noted that a mutex is obtained on the call to Begin() which will prevent any other threads from using the trace stream until the End() function is called.

So a typical usage would be:


  ostream & s = PTrace::Begin(3, FILE, LINE);
  s << "hello";
  if (want_there)
    s << " there";
  s << '!' << PTrace::End;

Parameters

level	Log level for output
fileName	Filename of source file being traced
lineNum	Line number of source file being traced.
instance	Instance for object logging occurred in
module	Module or subsection string

static ostream& PTrace::Begin	(	unsigned	level,
		const char *	fileName,
		int	lineNum,
		const char *	module,
		const PObject *	instance,
		const char *	defModule
	)

inlinestatic

Parameters

level	Log level for output
fileName	Filename of source file being traced
lineNum	Line number of source file being traced.
module	Module or subsection string
instance	Instance for object logging occurred in

static ostream& PTrace::Begin	(	unsigned	level,
		const char *	fileName,
		int	lineNum,
		const PObject *	instance,
		const PObject *	defInstance,
		const char *	module
	)

inlinestatic

Parameters

level	Log level for output
fileName	Filename of source file being traced
lineNum	Line number of source file being traced.
instance	Instance for object logging occurred in
module	Module or subsection string

static PBoolean PTrace::CanTrace ( unsigned level )

static

Determine if the level may cause trace output.

This checks against the current global trace level set by SetLevel() for if the trace output may be emitted. This is used by the PTRACE() macro.

Parameters

level Trace level to check

static bool PTrace::CanTrace ( const ThrottleBase & throttle )

inlinestatic

References CanTrace().

Referenced by CanTrace().

static void PTrace::ClearOptions ( unsigned options )

static

Clear the trace options.

The PTRACE(), PTRACE_BLOCK() and PTRACE_LINE() macros output trace text that may contain assorted values. These are defined by the Options enum.

Note this function AND's the complement of the bits included in the options parameter.

Parameters

options Option bits to turn off

static ostream& PTrace::End ( ostream & strm )

static

End a trace output.

If the trace stream output is used outside of the provided macros, the End() function must be used at the end of the section of trace output. A mutex is obtained on the call to Begin() which will prevent any other threads from using the trace stream until the End(). The End() is used in a similar manner to std::endl or std::flush.

So a typical usage would be:


  ostream & s = PTrace::Begin();
  s << "hello";
  if (want_there)
    s << " there";
  s << '!' << PTrace::End;

Parameters

strm	Trace output stream being completed

static const char* PTrace::GetFilename ( )

static

Get the current filename for trace output.

Note that the returned pointer is only valid until the next call to SetFilename() or Initialise().

static unsigned PTrace::GetLevel ( )

static

Get the trace level.

The PTRACE() macro checks to see if its level is equal to or lower then the level set by this function. If so then the trace text is output to the trace stream.

static PINDEX PTrace::GetMaxLength ( )

static

Get the mmaximum length for logs.

Default is 10k

static unsigned PTrace::GetNextContextIdentifier ( )

static

static unsigned PTrace::GetOptions ( )

static

Get the current trace options.

The PTRACE(), PTRACE_BLOCK() and PTRACE_LINE() macros output trace text that may contain assorted values. These are defined by the Options enum.

static std::string PTrace::GetOptionsByName ( )

static

Get current trace options by name.

static ostream* PTrace::GetStream ( )

static

Get the stream being used for trace output.

static int PTrace::GetTimeZone ( )

static

Get the time zone being used for logging.

static void PTrace::Initialise	(	const PArgList &	args,
		unsigned	options = `Timestamp\|Thread\|Blocks`,
		const char *	traceCount = `PTRACE_ARG_TRACE`,
		const char *	outputFile = `PTRACE_ARG_OUTPUT`,
		const char *	traceOpts = `PTRACE_ARG_OPTION`,
		const char *	traceRollover = `PTRACE_ARG_ROLLOVER`,
		const char *	traceLevel = `PTRACE_ARG_LEVEL`
	)

static

Set the most common trace options.

This sets trace options based on command line arguments.

Parameters

args	Command line arguments
options	Default Options for tracing
traceCount	Argument option name for trace count
outputFile	Argument option name for log output file
traceOpts	Argument option name for trace options
traceRollover	Argument option name for trace file roll over pattern
traceLevel	Argument option name for trace level

static void PTrace::Initialise	(	unsigned	level,
		const char *	filename = `NULL`,
		unsigned	options = `Timestamp\|Thread\|Blocks`,
		const char *	rolloverPattern = `NULL`
	)

static

Set the most common trace options.

If filename is not NULL then a PTextFile is created and attached the trace output stream. This object is never closed or deleted until the termination of the program.

There are several special values for filename:

"stderr": Output to standard error
"stdout": Output to standard output
"DEBUGSTREAM": Output to debugger (Windows only)
"syslog,ident,priority,options,facility": Output to syslog (Unix variants only) The ident, priority, options & facility components are optional, so "syslog", "syslog,myappname", "syslog,myappname,3" are all acceptable. See PSystemLogToSyslog for their exact meaning.
"network,host:port,facility": Output to RFC3164 network log server. The server and facility components are optional. The default server would be "localhost" Also, the port is an optional field for the server component, defaulting to the RFC3164 standard value. So, "network,10.0.1.1" or "network,fred:1234" are acceptable. See PSystemLogToNetwork for more.

If rolloverPattern is not NULL it is used as the time format pattern appended to filename if the RotateLogMask bits are set. Default is "yyyy_MM_dd".

A trace output of the program name, version, OS abnd other information is written to the log immediately.

Parameters

level	Level for tracing
filename	Filename for log output
options	Options for tracing
rolloverPattern	Pattern for rolling over trace files

static void PTrace::Initialise	(	unsigned	level,
		const char *	filename,
		const char *	rolloverPattern,
		unsigned	options = `Timestamp \| Thread \| Blocks`
	)

inlinestatic

static ostream& PTrace::PrintInfo	(	ostream &	strm,
		bool	crlf = `true`
	)

static

Output trace parameters (level, output, options etc) to stream.

static void PTrace::SetFilename ( const char * filename )

static

Set the trace output file.

Parameters

filename New output file for tracing

static void PTrace::SetLevel ( unsigned level )

static

Set the trace level.

The PTRACE() macro checks to see if its level is equal to or lower then the level set by this function. If so then the trace text is output to the trace stream.

Parameters

level New level for tracing

static void PTrace::SetMaxLength ( PINDEX length )

static

Set the mmaximum length for logs.

Default is 10k

Parameters

length Maximum line length for log

static void PTrace::SetOptions ( unsigned options )

static

Set the trace options.

The PTRACE(), PTRACE_BLOCK() and PTRACE_LINE() macros output trace text that may contain assorted values. These are defined by the Options enum.

Note this function OR's the bits included in the options parameter.

Parameters

options New option bits for tracing

static void PTrace::SetOptionsByName ( const char * options )

static

Set the trace options by name.

The parameter string consists of a series of keywords separated by a + or -. Use +X or -X to add/remove option where X is one of: block PTrace::Block constructs in output time time since prgram start date date and time gmt Date/time is in UTC thread thread name and identifier level log level file source file name and line number object PObject pointer context context identifier single single line output daily rotate output file daily hour rotate output file hourly minute rotate output file every minute append append to output file, otherwise overwrites <perm> file permission similar to unix chmod, but starts with +/- and only has one combination at a time, e.g. +uw is user write, +or is other read, etc"

Parameters

options New option bits for tracing

static void PTrace::SetStream ( ostream * out )

static

Set the stream to be used for trace output.

This stream is used for all trace output using the various trace functions and macros.

Parameters

out	New output stream from trace.

static void PTrace::WalkStack	(	ostream &	strm,
		PThreadIdentifier	id = `PNullThreadIdentifier`,
		PUniqueThreadIdentifier	uid = `0`,
		bool	noSymbols = `false`
	)

static

Member Data Documentation

unsigned PTrace::MaxStackWalk

static

The documentation for this class was generated from the following file:

object.h

Classes

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Member Data Documentation