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 // Modified By:
27 //
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 #include <Pegasus/Common/TraceComponents.h>
39 #include <Pegasus/Common/TraceFileHandler.h>
40
41
42 PEGASUS_NAMESPACE_BEGIN
43 mike 1.2
44 /** Tracer implements tracing of messages to a defined file
45 */
46
47 class PEGASUS_COMMON_LINKAGE Tracer
48 {
49 public:
50
51 /** Levels of trace
52 Trace messages are written to the trace file only if they are at or
53 above a given trace level
54 LEVEL1 - Function Entry/Exit
55 LEVEL2 - Basic flow trace messages, low data detail
56 LEVEL3 - Inter-function logic flow, medium data detail
57 LEVEL4 - High data detail
58 */
59 static const Uint32 LEVEL1;
60 static const Uint32 LEVEL2;
61 static const Uint32 LEVEL3;
62 static const Uint32 LEVEL4;
63
64 mike 1.2 // PEGASUS_REMOVE_TRACE defines the compile time inclusion of the Trace
65 // interfaces. If defined the interfaces map to empty functions
66
67 #ifdef PEGASUS_REMOVE_TRACE
68
69 inline static void traceBuffer(
70 const char* fileName,
71 const Uint32 lineNum,
72 const Uint32 traceComponent,
73 const Uint32 traceLevel,
74 const char* data,
75 const Uint32 size)
76 {
77 // empty function
78 }
79 inline static void traceBuffer(
80 const Uint32 traceComponent,
81 const Uint32 traceLevel,
82 const char* data,
83 const Uint32 size)
84 {
85 mike 1.2 // empty function
86 }
87
88 inline static void trace(
89 const Uint32 traceComponent,
90 const Uint32 traceLevel,
91 const char *fmt,
92 ...)
93 {
94 // empty function
95 }
96
97 inline static void trace(
98 const char* fileName,
99 const Uint32 lineNum,
100 const Uint32 traceComponent,
101 const Uint32 traceLevel,
102 const char* fmt,
103 ...)
104 {
105 // empty function
106 mike 1.2 }
107
108 static Uint32 setTraceFile(const char* traceFile)
109 {
110 // empty function
111 return 0;
112 }
113
114 static Uint32 setTraceLevel(const Uint32 traceLevel)
115 {
116 // empty function
117 return 0;
118 }
119
120 static void setTraceComponents(
121 const String traceComponents)
122 {
123 // empty function
124 }
125
126
127 mike 1.2 #else
128 /** Traces the specified number of bytes in a given buffer
129 @param traceComponent component being traced
130 @param traceLevel trace level of the trace message
131 @param data buffer to be traced
132 @param size number of bytes to be traced
133 */
134 inline static void traceBuffer(
135 const Uint32 traceComponent,
136 const Uint32 traceLevel,
137 const char* data,
138 const Uint32 size)
139 {
140 _traceBuffer( traceComponent, traceLevel, data, size );
141 }
142
143 /** Traces the specified number of bytes in a given buffer
144 Overloaded to include the filename and the line number
145 of trace origin.
146 @param fileName filename of the trace originator
147 @param lineNum line number of the trace originator
148 mike 1.2 @param traceComponent component being traced
149 @param traceLevel trace level of the trace message
150 @param data buffer to be traced
151 @param size size of the buffer
152 */
153 inline static void traceBuffer(
154 const char* fileName,
155 const Uint32 lineNum,
156 const Uint32 traceComponent,
157 const Uint32 traceLevel,
158 const char* data,
159 const Uint32 size)
160 {
161 _traceBuffer( fileName, lineNum,
162 traceComponent, traceLevel, data, size );
163 }
164
165
166 /** Traces the given message
167 @param traceComponent component being traced
168 @param traceLevel trace level of the trace message
169 mike 1.2 @param *fmt printf style format string
170 @param ... variable argument list
171 */
172 inline static void trace(
173 const Uint32 traceComponent,
174 const Uint32 traceLevel,
175 const char *fmt,
176 ...)
177 {
178 va_list argList;
179
180 va_start(argList,fmt);
181 _trace(traceComponent,traceLevel,fmt,argList);
182 va_end(argList);
183 }
184
185 /** Traces the given message. Overloaded to include the filename and
186 the line number of trace origin.
187 @param fileName filename of the trace originator
188 @param lineNum line number of the trace originator
189 @param traceComponent component being traced
190 mike 1.2 @param traceLevel trace level of the trace message
191 @param *fmt printf style format string
192 @param ... variable argument list
193 */
194 inline static void trace(
195 const char* fileName,
196 const Uint32 lineNum,
197 const Uint32 traceComponent,
198 const Uint32 traceLevel,
199 const char* fmt,
200 ...)
201 {
202 va_list argList;
203
204 va_start(argList,fmt);
205 _trace(fileName,lineNum,traceComponent,traceLevel,fmt,argList);
206 va_end(argList);
207 }
208
209 /** Set the trace file to the given file
210 @param traceFile full path of the trace file
211 mike 1.2 @return 0 if the filepath is valid
212 1 if an error occurs while opening the file
213 in append mode
214 */
215 static Uint32 setTraceFile(const char* traceFile);
216
217 /** Set the trace level to the given level
218 @param traceLevel trace level to be set
219 @return 0 if trace level is valid
220 1 if trace level is invalid
221 */
222 static Uint32 setTraceLevel(const Uint32 traceLevel);
223
224 /** Set components to be traced
225 @param traceComponents list of components to be traced,
226 components should be separated by ','
227 */
228 static void setTraceComponents(
229 const String traceComponents);
230
231 #endif
232 mike 1.2
233 // End of PEGASUS_REMOVE_TRACE
234
235 /** Traces method entry.
236 @param fileName filename of the trace originator
237 @param lineNum line number of the trace originator
238 @param traceComponent component being traced
239 @param methodName method being traced
240 */
241 inline static void traceEnter(
242 const char* fileName,
243 const Uint32 lineNum,
244 const Uint32 traceComponent,
245 const char* methodName)
246 {
247 _traceEnter( fileName, lineNum, traceComponent, "%s %s",
248 _FUNC_ENTER_MSG, methodName);
249 }
250
251 /** Traces method exit.
252 @param fileName filename of the trace originator
253 mike 1.2 @param lineNum line number of the trace originator
254 @param traceComponent component being traced
255 @param methodName method being traced
256 */
257 inline static void traceExit(
258 const char* fileName,
259 const Uint32 lineNum,
260 const Uint32 traceComponent,
261 const char* methodName)
262 {
263 _traceExit( fileName, lineNum, traceComponent, "%s %s",
264 _FUNC_EXIT_MSG, methodName);
265 }
266
267 /** Validates the File Path for the trace File
268 @param filePath full path of the file
269 @return 1 if the file path is valid
270 0 if the file path is invalid
271 */
272 static Boolean isValid(const char* filePath);
273
274 mike 1.2 /** Validates the trace components
275 @param traceComponents comma separated list of trace components
276 @param invalidComponents comma separated list of invalid components
277 @return 1 if the components are valid
278 0 if one or more components are invalid
279 */
280 static Boolean isValid(
281 const String traceComponents, String& invalidComponents=_EMPTY_STRING);
282
283 private:
284
285 static const char _COMPONENT_SEPARATOR;
286 static const Uint32 _NUM_COMPONENTS;
287 static const Uint32 _STRLEN_MAX_UNSIGNED_INT;
288 static const Boolean _SUCCESS;
289 static const Boolean _FAILURE;
290 static String _EMPTY_STRING;
291 Boolean* _traceComponentMask;
292 Uint32 _traceLevelMask;
293 TraceFileHandler* _traceHandler;
294 static Tracer* _tracerInstance;
295 mike 1.2
296 // Message Strings for fucntion Entry and Exit
297 static const char _FUNC_ENTER_MSG[];
298 static const char _FUNC_EXIT_MSG[];
299
300 // Message Strings for Logger
301 static const char _LOG_MSG1[];
302 static const char _LOG_MSG2[];
303 static const char _LOG_MSG3[];
304
305 // Checks if trace is enabled for the given component and trace level
306 // @param traceComponent component being traced
307 // @param traceLevel level of the trace message
308 // @return 0 if the component and level are not enabled
309 // 1 if the component and level are enabled
310 static Boolean _isTraceEnabled(
311 const Uint32 traceComponent,
312 const Uint32 traceLevel);
313
314 // Traces the given message
315 // @param traceComponent component being traced
316 mike 1.2 // @param traceLevel level of the trace message
317 // @param *fmt printf style format string
318 // @param argList variable argument list
319 static void _trace(
320 const Uint32 traceComponent,
321 const Uint32 traceLevel,
322 const char* fmt,
323 va_list argList);
324
325 // Traces the given message. Overloaded to include the file name and the
326 // line number as one of the parameters.
327 // @param traceComponent component being traced
328 // @param traceLevel level of the trace message
329 // @param message message header (file name:line number)
330 // @param *fmt printf style format string
331 // @param argList variable argument list
332 static void _trace(
333 const char* fileName,
334 const Uint32 lineNum,
335 const Uint32 traceComponent,
336 const Uint32 traceLevel,
337 mike 1.2 const char* fmt,
338 va_list argList);
339
340 // Traces the specified number of bytes in a given buffer
341 // @param traceComponent component being traced
342 // @param traceLevel trace level of the trace message
343 // @param data buffer to be traced
344 // @param size number of bytes to be traced
345 static void _traceBuffer(
346 const Uint32 traceComponent,
347 const Uint32 traceLevel,
348 const char* data,
349 const Uint32 size);
350
351 // Traces the specified number of bytes in a given buffer
352 // Overloaded to include the filename and the line number
353 // of trace origin.
354 // @param fileName filename of the trace originator
355 // @param lineNum line number of the trace originator
356 // @param traceComponent component being traced
357 // @param traceLevel trace level of the trace message
358 mike 1.2 // @param data buffer to be traced
359 // @param size size of the buffer
360 static void _traceBuffer(
361 const char* fileName,
362 const Uint32 lineNum,
363 const Uint32 traceComponent,
364 const Uint32 traceLevel,
365 const char* data,
366 const Uint32 size);
367
368 // Called by all the trace interfaces to log message to the
369 // trace file
370 // @param fileName filename of the trace originator
371 // @param lineNum line number of the trace originator
372 // @param traceComponent component being traced
373 // @param *fmt printf style format string
374 // @param argList variable argument list
375 static void _trace(
376 const Uint32 traceComponent,
377 const char* message,
378 const char* fmt,
379 mike 1.2 va_list argList);
380
381 // Traces method enter
382 // @param fileName filename of the trace originator
383 // @param lineNum line number of the trace originator
384 // @param traceComponent component being traced
385 // @param *fmt printf style format string
386 // @param ... variable argument list
387 static void _traceEnter(
388 const char* fileName,
389 const Uint32 lineNum,
390 const Uint32 traceComponent,
391 const char* fmt,
392 ...);
393
394 // Traces method exit
395 // @param fileName filename of the trace originator
396 // @param traceComponent component being traced
397 // @param *fmt printf style format string
398 // @param ... variable argument list
399 static void _traceExit(
400 mike 1.2 const char* fileName,
401 const Uint32 lineNum,
402 const Uint32 traceComponent,
403 const char* fmt,
404 ...);
405
406 // Tracer constructor
407 // Constructor is private to prevent construction of Tracer objects
408 // Single Instance of Tracer is maintained for each process.
409 Tracer();
410
411 // Tracer destructor
412 ~Tracer();
413
414 // Returns the Singleton instance of the Tracer
415 // @return Tracer* Instance of Tracer
416 static Tracer* _getInstance();
417 };
418
419 // Define the macros for method entry/exit
420 #ifdef PEGASUS_REMOVE_TRACE
421 mike 1.2 #define PEG_FUNC_ENTER(traceComponent,methodName)
422 #define PEG_FUNC_EXIT(traceComponent,methodName)
423 #else
424 /** Macro for tracing method entry
425 @param traceComponent component being traced
426 @param methodName name of the method
427 */
428 #define PEG_FUNC_ENTER(traceComponent,methodName) \
429 Tracer::traceEnter(__FILE__, __LINE__,traceComponent,methodName)
430
431 /** Macro for tracing method exit
432 @param traceComponent component being traced
433 @param methodName name of the method
434 */
435 #define PEG_FUNC_EXIT(traceComponent,methodName) \
436 Tracer::traceExit(__FILE__,__LINE__,traceComponent,methodName)
437 #endif
438
439 PEGASUS_NAMESPACE_END
440
441 #endif /* Pegasus_Tracer_h */
|