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