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