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