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

Return to Tracer.h CVS log

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

1 karl 1.18 //%2005////////////////////////////////////////////////////////////////////////
2 mike 1.2 //
3 karl 1.16 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development 4 // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems. 5 // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
6 karl 1.13 // IBM Corp.; EMC Corporation, The Open Group.
7 karl 1.16 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.; 8 // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
9 karl 1.18 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.; 10 // EMC Corporation; VERITAS Software Corporation; The Open Group.
11 mike 1.2 // 12 // Permission is hereby granted, free of charge, to any person obtaining a copy 13 // of this software and associated documentation files (the "Software"), to 14 // deal in the Software without restriction, including without limitation the 15 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 16 // sell copies of the Software, and to permit persons to whom the Software is 17 // furnished to do so, subject to the following conditions:
18 r.kieninger 1.20 //
19 mike 1.2 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN 20 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED 21 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 22 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR 23 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 24 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 25 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 26 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 27 // 28 //============================================================================== 29 // 30 // Author: Sushma Fernandes, Hewlett-Packard Company (sushma_fernandes@hp.com) 31 //
32 kumpf 1.6 // Modified By: Jenny Yu, Hewlett-Packard Company (jenny_yu@hp.com)
33 a.arora 1.14 // Amit K Arora, IBM (amita@in.ibm.com) for PEP#101
34 kumpf 1.15 // Roger Kumpf, Hewlett-Packard Company (roger_kumpf@hp.com)
35 mike 1.2 // 36 //%///////////////////////////////////////////////////////////////////////////// 37 38 #ifndef Pegasus_Tracer_h 39 #define Pegasus_Tracer_h 40 41 #include <stdarg.h> 42 #include <Pegasus/Common/String.h> 43 #include <Pegasus/Common/System.h> 44 #include <Pegasus/Common/Logger.h>
45 kumpf 1.12 #include <Pegasus/Common/InternalException.h>
46 mike 1.2 #include <Pegasus/Common/TraceComponents.h> 47 #include <Pegasus/Common/TraceFileHandler.h>
48 kumpf 1.11 #include <Pegasus/Common/Linkage.h>
49 a.arora 1.14 #include <Pegasus/Common/AutoPtr.h>
50 mike 1.2 51 PEGASUS_NAMESPACE_BEGIN 52 53 /** Tracer implements tracing of messages to a defined file 54 / 55 56 class PEGASUS_COMMON_LINKAGE Tracer 57 { 58 public: 59 60 /* Levels of trace 61 Trace messages are written to the trace file only if they are at or 62 above a given trace level 63 LEVEL1 - Function Entry/Exit 64 LEVEL2 - Basic flow trace messages, low data detail 65 LEVEL3 - Inter-function logic flow, medium data detail 66 LEVEL4 - High data detail 67 */ 68 static const Uint32 LEVEL1; 69 static const Uint32 LEVEL2; 70 static const Uint32 LEVEL3; 71 mike 1.2 static const Uint32 LEVEL4;
72 r.kieninger 1.20 73 // PEGASUS_REMOVE_TRACE defines the compile time inclusion of the Trace
74 mike 1.2 // interfaces. If defined the interfaces map to empty functions
75 r.kieninger 1.20
76 mike 1.2 #ifdef PEGASUS_REMOVE_TRACE
77 r.kieninger 1.20
78 mike 1.2 inline static void traceBuffer( 79 const char* fileName, 80 const Uint32 lineNum, 81 const Uint32 traceComponent, 82 const Uint32 traceLevel, 83 const char* data, 84 const Uint32 size) 85 { 86 // empty function 87 } 88 inline static void traceBuffer( 89 const Uint32 traceComponent, 90 const Uint32 traceLevel, 91 const char* data, 92 const Uint32 size) 93 { 94 // empty function 95 }
96 r.kieninger 1.20
97 mike 1.2 inline static void trace( 98 const Uint32 traceComponent, 99 const Uint32 traceLevel, 100 const char *fmt, 101 ...) 102 { 103 // empty function 104 }
105 r.kieninger 1.20
106 mike 1.2 inline static void trace( 107 const char* fileName, 108 const Uint32 lineNum, 109 const Uint32 traceComponent, 110 const Uint32 traceLevel, 111 const char* fmt, 112 ...) 113 { 114 // empty function 115 } 116
117 kumpf 1.6 inline static void trace( 118 const char* fileName, 119 const Uint32 lineNum, 120 const Uint32 traceComponent, 121 const Uint32 traceLevel, 122 const String& traceString) 123 { 124 // empty function 125 } 126 127 inline static void traceCIMException( 128 const Uint32 traceComponent, 129 const Uint32 traceLevel, 130 CIMException cimException) 131 { 132 // empty function 133 } 134
135 mike 1.2 static Uint32 setTraceFile(const char* traceFile) 136 { 137 // empty function 138 return 0; 139 } 140 141 static Uint32 setTraceLevel(const Uint32 traceLevel) 142 { 143 // empty function 144 return 0; 145 } 146 147 static void setTraceComponents(
148 kumpf 1.15 const String& traceComponents)
149 mike 1.2 { 150 // empty function 151 }
152 r.kieninger 1.20
153 mike 1.2 154 #else
155 r.kieninger 1.20 /** Traces the specified number of bytes in a given buffer
156 mike 1.2 @param traceComponent component being traced 157 @param traceLevel trace level of the trace message 158 @param data buffer to be traced
159 r.kieninger 1.20 @param size number of bytes to be traced
160 mike 1.2 / 161 inline static void traceBuffer( 162 const Uint32 traceComponent, 163 const Uint32 traceLevel, 164 const char data, 165 const Uint32 size) 166 {
167 r.kieninger 1.20 if (_traceOn) 168 { 169 _traceBuffer( traceComponent, traceLevel, data, size ); 170 }
171 mike 1.2 }
172 r.kieninger 1.20 173 /** Traces the specified number of bytes in a given buffer 174 Overloaded to include the filename and the line number 175 of trace origin.
176 mike 1.2 @param fileName filename of the trace originator 177 @param lineNum line number of the trace originator 178 @param traceComponent component being traced 179 @param traceLevel trace level of the trace message 180 @param data buffer to be traced 181 @param size size of the buffer 182 / 183 inline static void traceBuffer( 184 const char fileName, 185 const Uint32 lineNum, 186 const Uint32 traceComponent, 187 const Uint32 traceLevel, 188 const char* data, 189 const Uint32 size) 190 {
191 r.kieninger 1.20 if (_traceOn) 192 { 193 _traceBuffer( fileName, lineNum, 194 traceComponent, traceLevel, data, size ); 195 }
196 mike 1.2 }
197 r.kieninger 1.20 198 199 /** Traces the given message
200 mike 1.2 @param traceComponent component being traced 201 @param traceLevel trace level of the trace message 202 @param fmt printf style format string 203 @param ... variable argument list 204 / 205 inline static void trace( 206 const Uint32 traceComponent, 207 const Uint32 traceLevel, 208 const char *fmt, 209 ...) 210 {
211 r.kieninger 1.20 if (_traceOn) 212 { 213 va_list argList; 214 215 va_start(argList,fmt); 216 _trace(traceComponent,traceLevel,fmt,argList); 217 va_end(argList); 218 } 219 } 220 221 /** Traces the given message. Overloaded to include the filename and 222 the line number of trace origin.
223 mike 1.2 @param fileName filename of the trace originator 224 @param lineNum line number of the trace originator 225 @param traceComponent component being traced 226 @param traceLevel trace level of the trace message 227 @param fmt printf style format string 228 @param ... variable argument list 229 / 230 inline static void trace( 231 const char* fileName, 232 const Uint32 lineNum, 233 const Uint32 traceComponent, 234 const Uint32 traceLevel, 235 const char* fmt, 236 ...) 237 {
238 r.kieninger 1.20 if (_traceOn) 239 { 240 va_list argList; 241 242 va_start(argList,fmt); 243 _trace(fileName,lineNum,traceComponent,traceLevel,fmt,argList); 244 va_end(argList); 245 }
246 mike 1.2 } 247
248 kumpf 1.6 /** Traces the given string. Overloaded to include the filename 249 and line number of trace origin. 250 @param fileName filename of the trace originator 251 @param lineNum line number of the trace originator 252 @param traceComponent component being traced 253 @param traceLevel trace level of the trace message 254 @param traceString the string to be traced 255 / 256 inline static void trace( 257 const char fileName, 258 const Uint32 lineNum, 259 const Uint32 traceComponent, 260 const Uint32 traceLevel, 261 const String& traceString) 262 {
263 r.kieninger 1.20 if (_traceOn) 264 { 265 _traceString( fileName, lineNum, traceComponent, traceLevel, 266 traceString ); 267 }
268 kumpf 1.6 } 269 270 /** Traces the message in the given CIMException object. The message 271 written to the trace file will include the source filename and 272 line number of the CIMException originator. 273 @param traceComponent component being traced 274 @param traceLevel trace level of the trace message 275 @param CIMException the CIMException to be traced. 276 */ 277 inline static void traceCIMException( 278 const Uint32 traceComponent, 279 const Uint32 traceLevel, 280 CIMException cimException) 281 {
282 r.kieninger 1.20 if (_traceOn) 283 { 284 _traceCIMException( traceComponent, traceLevel, cimException ); 285 }
286 kumpf 1.6 } 287
288 mike 1.2 /** Set the trace file to the given file 289 @param traceFile full path of the trace file
290 r.kieninger 1.20 @return 0 if the filepath is valid
291 kumpf 1.17 1 if the traceFile is an empty string or 292 if an error occurs while opening the file
293 mike 1.2 in append mode 294 / 295 static Uint32 setTraceFile(const char traceFile); 296 297 /** Set the trace level to the given level 298 @param traceLevel trace level to be set 299 @return 0 if trace level is valid 300 1 if trace level is invalid 301 / 302 static Uint32 setTraceLevel(const Uint32 traceLevel); 303 304 /* Set components to be traced
305 r.kieninger 1.20 @param traceComponents list of components to be traced,
306 mike 1.2 components should be separated by ',' 307 */ 308 static void setTraceComponents(
309 kumpf 1.15 const String& traceComponents);
310 r.kieninger 1.20 311 #endif
312 mike 1.2 313 // End of PEGASUS_REMOVE_TRACE
314 r.kieninger 1.20 315 /** Traces method entry.
316 mike 1.2 @param fileName filename of the trace originator 317 @param lineNum line number of the trace originator 318 @param traceComponent component being traced 319 @param methodName method being traced 320 / 321 inline static void traceEnter( 322 const char fileName, 323 const Uint32 lineNum, 324 const Uint32 traceComponent, 325 const char* methodName) 326 {
327 r.kieninger 1.20 if (_traceOn) 328 { 329 _traceEnter( fileName, lineNum, traceComponent, "%s %s", 330 _METHOD_ENTER_MSG, methodName); 331 }
332 mike 1.2 }
333 r.kieninger 1.20 334 /** Traces method exit.
335 mike 1.2 @param fileName filename of the trace originator 336 @param lineNum line number of the trace originator 337 @param traceComponent component being traced 338 @param methodName method being traced 339 / 340 inline static void traceExit( 341 const char fileName, 342 const Uint32 lineNum, 343 const Uint32 traceComponent, 344 const char* methodName) 345 {
346 r.kieninger 1.20 if (_traceOn) 347 { 348 _traceExit( fileName, lineNum, traceComponent, "%s %s", 349 _METHOD_EXIT_MSG, methodName); 350 }
351 mike 1.2 } 352 353 /** Validates the File Path for the trace File
354 r.kieninger 1.20 @param filePath full path of the file
355 mike 1.2 @return 1 if the file path is valid 356 0 if the file path is invalid 357 */
358 kumpf 1.7 static Boolean isValidFileName(const char* filePath); 359 360 /** Validates the trace components 361 @param traceComponents comma separated list of trace components 362 @return 1 if the components are valid 363 0 if one or more components are invalid 364 */
365 kumpf 1.15 static Boolean isValidComponents(const String& traceComponents);
366 mike 1.2 367 /** Validates the trace components 368 @param traceComponents comma separated list of trace components 369 @param invalidComponents comma separated list of invalid components 370 @return 1 if the components are valid 371 0 if one or more components are invalid 372 */
373 kumpf 1.7 static Boolean isValidComponents(
374 kumpf 1.15 const String& traceComponents,
375 kumpf 1.7 String& invalidComponents);
376 mike 1.2
377 kumpf 1.15 /** Specify the name of the module being traced. If non-empty, this 378 value is used as an extension to the name of the trace file. 379 @param moduleName Name of the module being traced. 380 */ 381 static void setModuleName(const String& moduleName); 382
383 mike 1.21 static bool isTraceOn() { return _traceOn; } 384
385 mike 1.2 private: 386
387 r.kieninger 1.20 /** A static single indicator if tracing is turned on allowing to 388 determine the state of trace quickly without many instructions. 389 Used to wrap the public static trace interface methods to avoid 390 obsolete calls when tracing is turned off. 391 */ 392 static Uint32 _traceOn; 393
394 mike 1.2 static const char _COMPONENT_SEPARATOR; 395 static const Uint32 _NUM_COMPONENTS; 396 static const Uint32 _STRLEN_MAX_UNSIGNED_INT;
397 kumpf 1.4 static const Uint32 _STRLEN_MAX_PID_TID;
398 mike 1.2 static const Boolean _SUCCESS; 399 static const Boolean _FAILURE;
400 kumpf 1.15 AutoArrayPtr<Boolean> _traceComponentMask;
401 mike 1.2 Uint32 _traceLevelMask;
402 kumpf 1.15 AutoPtr<TraceFileHandler> _traceHandler; 403 String _moduleName;
404 mike 1.2 static Tracer* _tracerInstance; 405
406 kumpf 1.10 // Message Strings for function Entry and Exit
407 r.kieninger 1.20 static const char _METHOD_ENTER_MSG[]; 408 static const char _METHOD_EXIT_MSG[];
409 mike 1.2 410 // Message Strings for Logger
411 r.kieninger 1.20 static const char _LOG_MSG[];
412 mike 1.2 413 // Checks if trace is enabled for the given component and trace level 414 // @param traceComponent component being traced 415 // @param traceLevel level of the trace message
416 r.kieninger 1.20 // @return 0 if the component and level are not enabled 417 // 1 if the component and level are enabled
418 mike 1.2 static Boolean _isTraceEnabled( 419 const Uint32 traceComponent, 420 const Uint32 traceLevel); 421
422 r.kieninger 1.20 // Traces the given message
423 mike 1.2 // @param traceComponent component being traced 424 // @param traceLevel level of the trace message 425 // @param fmt printf style format string 426 // @param argList variable argument list 427 static void _trace( 428 const Uint32 traceComponent, 429 const Uint32 traceLevel, 430 const char fmt, 431 va_list argList); 432 433 // Traces the given message. Overloaded to include the file name and the 434 // line number as one of the parameters. 435 // @param traceComponent component being traced 436 // @param traceLevel level of the trace message 437 // @param message message header (file name:line number) 438 // @param fmt printf style format string 439 // @param argList variable argument list 440 static void _trace( 441 const char fileName, 442 const Uint32 lineNum, 443 const Uint32 traceComponent, 444 mike 1.2 const Uint32 traceLevel, 445 const char* fmt, 446 va_list argList); 447 448 // Traces the specified number of bytes in a given buffer 449 // @param traceComponent component being traced 450 // @param traceLevel trace level of the trace message 451 // @param data buffer to be traced 452 // @param size number of bytes to be traced 453 static void _traceBuffer( 454 const Uint32 traceComponent, 455 const Uint32 traceLevel, 456 const char* data, 457 const Uint32 size); 458 459 // Traces the specified number of bytes in a given buffer 460 // Overloaded to include the filename and the line number 461 // of trace origin. 462 // @param fileName filename of the trace originator 463 // @param lineNum line number of the trace originator 464 // @param traceComponent component being traced 465 mike 1.2 // @param traceLevel trace level of the trace message 466 // @param data buffer to be traced 467 // @param size size of the buffer 468 static void _traceBuffer( 469 const char* fileName, 470 const Uint32 lineNum, 471 const Uint32 traceComponent, 472 const Uint32 traceLevel, 473 const char* data, 474 const Uint32 size); 475
476 kumpf 1.6 // Traces the given string. 477 // @param traceComponent component being traced 478 // @param traceLevel trace level of the trace message 479 // @param traceString the string to be traced 480 // 481 static void _traceString( 482 const Uint32 traceComponent, 483 const Uint32 traceLevel, 484 const String& traceString); 485 486 // Traces a given string. Overloaded to include the filename 487 // and line number of trace origin. 488 // @param fileName filename of the trace originator 489 // @param lineNum line number of the trace originator 490 // @param traceComponent component being traced 491 // @param traceLevel trace level of the trace message 492 // @param traceString the string to be traced 493 // 494 static void _traceString( 495 const char* fileName, 496 const Uint32 lineNum, 497 kumpf 1.6 const Uint32 traceComponent, 498 const Uint32 traceLevel, 499 const String& traceString); 500 501 // Traces the message in the given CIMException object. The message
502 r.kieninger 1.20 // to be written to the trace file will include the source filename and
503 kumpf 1.6 // line number of the CIMException originator. 504 // @param traceComponent component being traced 505 // @param traceLevel trace level of the trace message 506 // @param CIMException the CIMException to be traced. 507 // 508 static void _traceCIMException( 509 const Uint32 traceComponent, 510 const Uint32 traceLevel, 511 CIMException cimException);
512 r.kieninger 1.20 513 // Called by all the trace interfaces to log message to the
514 mike 1.2 // trace file 515 // @param fileName filename of the trace originator 516 // @param lineNum line number of the trace originator 517 // @param traceComponent component being traced 518 // @param fmt printf style format string 519 // @param argList variable argument list 520 static void _trace( 521 const Uint32 traceComponent, 522 const char message, 523 const char* fmt, 524 va_list argList); 525 526 // Traces method enter 527 // @param fileName filename of the trace originator 528 // @param lineNum line number of the trace originator 529 // @param traceComponent component being traced 530 // @param fmt printf style format string 531 // @param ... variable argument list 532 static void _traceEnter( 533 const char fileName, 534 const Uint32 lineNum, 535 mike 1.2 const Uint32 traceComponent, 536 const char* fmt, 537 ...); 538 539 // Traces method exit 540 // @param fileName filename of the trace originator 541 // @param traceComponent component being traced 542 // @param fmt printf style format string 543 // @param ... variable argument list 544 static void _traceExit( 545 const char fileName, 546 const Uint32 lineNum, 547 const Uint32 traceComponent, 548 const char* fmt, 549 ...); 550 551 // Tracer constructor 552 // Constructor is private to prevent construction of Tracer objects 553 // Single Instance of Tracer is maintained for each process. 554 Tracer(); 555 556 mike 1.2 // Tracer destructor 557 ~Tracer(); 558 559 // Returns the Singleton instance of the Tracer
560 r.kieninger 1.20 // @return Tracer* Instance of Tracer
561 mike 1.2 static Tracer* _getInstance(); 562 }; 563
564 kumpf 1.6 // Define the macros for method entry/exit, and tracing a given string
565 mike 1.2 #ifdef PEGASUS_REMOVE_TRACE
566 mike 1.22 # define PEG_METHOD_ENTER(traceComponent,methodName) 567 # define PEG_METHOD_EXIT() 568 # define PEG_TRACE_STRING(traceComponent,traceLevel,traceString) 569 # define PEG_TRACE(VAR_ARGS)
570 mike 1.2 #else
571 kumpf 1.5 /** Macro for tracing method entry 572 @param traceComponent component being traced 573 @param methodName name of the method 574 */
575 mike 1.22 # define PEG_METHOD_ENTER(traceComponent,methodName) \ 576 static const char *PEG_METHOD_NAME = methodName; \ 577 static const Uint32 PEG_TRACE_COMPONENT = traceComponent; \ 578 if (Tracer::isTraceOn()) \ 579 { \ 580 Tracer::traceEnter( \ 581 __FILE__,__LINE__,PEG_TRACE_COMPONENT,PEG_METHOD_NAME); \ 582 } \
583 kumpf 1.5 584 /** Macro for tracing method exit 585 */
586 mike 1.22 # define PEG_METHOD_EXIT() \ 587 do \ 588 { \ 589 if (Tracer::isTraceOn()) \ 590 Tracer::traceExit( \ 591 __FILE__,__LINE__,PEG_TRACE_COMPONENT,PEG_METHOD_NAME); \ 592 } \ 593 while (0)
594 kumpf 1.6 595 /** Macro for tracing a string 596 @param traceComponent component being traced 597 @param traceLevel trace level of the trace message 598 @param traceString the string to be traced 599 */
600 mike 1.22 # define PEG_TRACE_STRING(traceComponent,traceLevel,traceString) \
601 mike 1.21 do \ 602 { \ 603 if (Tracer::isTraceOn()) \ 604 Tracer::trace( \ 605 __FILE__, __LINE__,traceComponent,traceLevel,traceString); \ 606 } \ 607 while (0)
608 mday 1.8
609 mike 1.22 # define PEG_TRACE(VAR_ARGS) \ 610 do \ 611 { \ 612 if (Tracer::isTraceOn()) \ 613 Tracer::trace VAR_ARGS; \ 614 } \ 615 while (0) 616
617 mike 1.2 #endif 618 619 PEGASUS_NAMESPACE_END 620 621 #endif /* Pegasus_Tracer_h */

No CVS admin address has been configured