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 marek 1.31 #include <cstdarg>
|
38 mike 1.2 #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 sushma.fernandes 1.30 #include <Pegasus/Common/SharedPtr.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 marek 1.28 /** Traces the given character string.
77 Overloaded to include the filename
78 and line number of trace origin.
|
79 kumpf 1.27 @param fileName filename of the trace originator
80 @param lineNum line number of the trace originator
81 @param traceComponent component being traced
|
82 marek 1.28 @param cstring the character string to be traced
|
83 karl 1.25 */
|
84 marek 1.28 static void traceCString(
85 const char* fileName,
86 const Uint32 lineNum,
|
87 kumpf 1.27 const Uint32 traceComponent,
|
88 marek 1.28 const char* cstring);
|
89 karl 1.25
90 /** Traces the message in the given CIMException object. The message
|
91 kumpf 1.27 written to the trace file will include the source filename and
92 line number of the CIMException originator.
93 @param traceComponent component being traced
94 @param level trace level of the trace message
95 @param CIMException the CIMException to be traced.
|
96 karl 1.25 */
97 static void traceCIMException(
|
98 kumpf 1.27 const Uint32 traceComponent,
99 const Uint32 level,
100 const CIMException& cimException);
|
101 karl 1.25
|
102 sushma.fernandes 1.30 /** Gets an HTTP request message.
103
104 Given an HTTP request message, this method checks if the
105 message contains a "Basic" authorization header.
106
107 If true, the username/passwd is suppressed and returned.
108 Otherwise the request message is returned without any changes.
109
110 @param requestMessage requestMessage to be checked
111
112 @return request message
113
114 */
115 static SharedArrayPtr<char> getHTTPRequestMessage(
116 const Buffer& requestMessage);
117
|
118 karl 1.25 /** Set the trace file to the given file
|
119 kumpf 1.27 @param traceFile full path of the trace file
120 @return 0 if the filepath is valid
121 1 if the traceFile is an empty string or
122 if an error occurs while opening the file
123 in append mode
|
124 karl 1.25 */
125 static Uint32 setTraceFile(const char* traceFile);
126
127 /** Set the trace level to the given level
|
128 kumpf 1.27 @param level trace level to be set
129 @return 0 if trace level is valid
130 1 if trace level is invalid
|
131 karl 1.25 */
132 static Uint32 setTraceLevel(const Uint32 level);
133
134 /** Set components to be traced
|
135 kumpf 1.27 @param traceComponents list of components to be traced,
136 components should be separated by ','
|
137 karl 1.25 */
138 static void setTraceComponents(
139 const String& traceComponents);
|
140 r.kieninger 1.20
|
141 karl 1.25 /** Traces method entry.
|
142 kumpf 1.27 @param token TracerToken
143 @param fileName filename of the trace originator
144 @param lineNum line number of the trace originator
145 @param traceComponent component being traced
146 @param methodName method being traced
|
147 mike 1.2 */
|
148 karl 1.25 static void traceEnter(
|
149 kumpf 1.27 TracerToken& token,
150 const char* file,
151 size_t line,
152 Uint32 component,
153 const char* method);
|
154 r.kieninger 1.20
155 /** Traces method exit.
|
156 kumpf 1.27 @param token TracerToken containing component and method
157 @param fileName filename of the trace originator
158 @param lineNum line number of the trace originator
|
159 mike 1.2 */
|
160 karl 1.25 static void traceExit(
|
161 kumpf 1.27 TracerToken& token,
162 const char* file,
163 size_t line);
|
164 mike 1.2
165 /** Validates the File Path for the trace File
|
166 kumpf 1.27 @param filePath full path of the file
167 @return 1 if the file path is valid
168 0 if the file path is invalid
|
169 mike 1.2 */
|
170 kumpf 1.7 static Boolean isValidFileName(const char* filePath);
171
172 /** Validates the trace components
|
173 kumpf 1.27 @param traceComponents comma separated list of trace components
174 @return 1 if the components are valid
175 0 if one or more components are invalid
|
176 kumpf 1.7 */
|
177 kumpf 1.15 static Boolean isValidComponents(const String& traceComponents);
|
178 mike 1.2
179 /** Validates the trace components
|
180 kumpf 1.27 @param traceComponents comma separated list of trace components
181 @param invalidComponents comma separated list of invalid components
182 @return 1 if the components are valid
183 0 if one or more components are invalid
|
184 mike 1.2 */
|
185 kumpf 1.7 static Boolean isValidComponents(
|
186 kumpf 1.15 const String& traceComponents,
|
187 kumpf 1.7 String& invalidComponents);
|
188 mike 1.2
|
189 kumpf 1.15 /** Specify the name of the module being traced. If non-empty, this
190 value is used as an extension to the name of the trace file.
|
191 kumpf 1.27 @param moduleName Name of the module being traced.
|
192 kumpf 1.15 */
193 static void setModuleName(const String& moduleName);
194
|
195 karl 1.25 /**
196 */
|
197 david.dillard 1.23 static Boolean isTraceOn() { return _traceOn; }
|
198 mike 1.21
|
199 marek 1.31 // Checks if trace is enabled for the given component and trace level
200 // @param traceComponent component being traced
201 // @param level level of the trace message
202 // @return 0 if the component and level are not enabled
203 // 1 if the component and level are enabled
204 static Boolean isTraceEnabled(
205 const Uint32 traceComponent,
206 const Uint32 level);
207
|
208 mike 1.2 private:
209
|
210 r.kieninger 1.20 /** A static single indicator if tracing is turned on allowing to
211 determine the state of trace quickly without many instructions.
212 Used to wrap the public static trace interface methods to avoid
213 obsolete calls when tracing is turned off.
214 */
|
215 david.dillard 1.23 static Boolean _traceOn;
|
216 r.kieninger 1.20
|
217 mike 1.2 static const char _COMPONENT_SEPARATOR;
218 static const Uint32 _NUM_COMPONENTS;
219 static const Uint32 _STRLEN_MAX_UNSIGNED_INT;
|
220 kumpf 1.4 static const Uint32 _STRLEN_MAX_PID_TID;
|
221 mike 1.2 static const Boolean _SUCCESS;
222 static const Boolean _FAILURE;
|
223 kumpf 1.15 AutoArrayPtr<Boolean> _traceComponentMask;
|
224 mike 1.2 Uint32 _traceLevelMask;
|
225 kumpf 1.15 AutoPtr<TraceFileHandler> _traceHandler;
226 String _moduleName;
|
227 mike 1.2 static Tracer* _tracerInstance;
228
|
229 kumpf 1.10 // Message Strings for function Entry and Exit
|
230 r.kieninger 1.20 static const char _METHOD_ENTER_MSG[];
231 static const char _METHOD_EXIT_MSG[];
|
232 mike 1.2
233 // Message Strings for Logger
|
234 r.kieninger 1.20 static const char _LOG_MSG[];
|
235 mike 1.2
236 // Traces the given message. Overloaded to include the file name and the
237 // line number as one of the parameters.
238 // @param traceComponent component being traced
239 // @param message message header (file name:line number)
240 // @param *fmt printf style format string
241 // @param argList variable argument list
242 static void _trace(
|
243 kumpf 1.27 const char* fileName,
244 const Uint32 lineNum,
245 const Uint32 traceComponent,
246 const char* fmt,
247 va_list argList);
|
248 mike 1.2
|
249 kumpf 1.6 // Traces the message in the given CIMException object. The message
|
250 r.kieninger 1.20 // to be written to the trace file will include the source filename and
|
251 kumpf 1.6 // line number of the CIMException originator.
252 // @param traceComponent component being traced
253 // @param CIMException the CIMException to be traced.
254 //
255 static void _traceCIMException(
|
256 kumpf 1.27 const Uint32 traceComponent,
257 const CIMException& cimException);
|
258 r.kieninger 1.20
|
259 marek 1.28 // Called by all the trace interfaces to log message
260 // consisting of a single character string to the trace file
261 // @param traceComponent component being traced
262 // @param cstring the string to be traced
263 static void _traceCString(
264 const Uint32 traceComponent,
265 const char* message,
266 const char* cstring);
267
268 // Called by all the trace interfaces to log message
269 // with variable number of arguments to the trace file
|
270 mike 1.2 // @param traceComponent component being traced
271 // @param *fmt printf style format string
272 // @param argList variable argument list
273 static void _trace(
|
274 kumpf 1.27 const Uint32 traceComponent,
275 const char* message,
276 const char* fmt,
277 va_list argList);
|
278 mike 1.2
|
279 marek 1.28 // Traces method enter/exit
|
280 mike 1.2 // @param fileName filename of the trace originator
281 // @param lineNum line number of the trace originator
282 // @param traceComponent component being traced
|
283 marek 1.28 // @param method name of the method
284 static void _traceMethod(
|
285 kumpf 1.27 const char* fileName,
286 const Uint32 lineNum,
287 const Uint32 traceComponent,
|
288 marek 1.28 const char* methodEntryExit,
289 const char* method);
|
290 mike 1.2
291 // Tracer constructor
292 // Constructor is private to prevent construction of Tracer objects
293 // Single Instance of Tracer is maintained for each process.
294 Tracer();
295
296 // Tracer destructor
297 ~Tracer();
298
299 // Returns the Singleton instance of the Tracer
|
300 r.kieninger 1.20 // @return Tracer* Instance of Tracer
|
301 mike 1.2 static Tracer* _getInstance();
|
302 marek 1.31
303 friend class TraceCallFrame;
|
304 mike 1.2 };
305
|
306 karl 1.25 //==============================================================================
307 //
308 // PEGASUS_REMOVE_TRACE defines the compile time inclusion of the Trace
309 // interfaces. If defined the interfaces map to empty functions.
310 //
311 //==============================================================================
312
|
313 mike 1.2 #ifdef PEGASUS_REMOVE_TRACE
|
314 karl 1.25
|
315 marek 1.28 inline void Tracer::traceCString(
316 const char* fileName,
317 const Uint32 lineNum,
|
318 kumpf 1.27 const Uint32 traceComponent,
|
319 marek 1.28 const char* cstring)
|
320 karl 1.25 {
321 // empty function
322 }
323
324 inline void Tracer::traceCIMException(
|
325 kumpf 1.27 const Uint32 traceComponent,
326 const Uint32 level,
327 const CIMException& cimException)
|
328 karl 1.25 {
329 // empty function
330 }
331
|
332 sushma.fernandes 1.30 static SharedArrayPtr<char> getHTTPRequestMessage(
333 const Buffer& requestMessage)
334 {
335 //empty function
336 return SharedArrayPtr<char>();
337 }
338
|
339 karl 1.25 inline Uint32 Tracer::setTraceFile(const char* traceFile)
340 {
341 // empty function
342 return 0;
343 }
344
|
345 kumpf 1.26 inline Uint32 Tracer::setTraceLevel(const Uint32 level)
346 {
347 // empty function
348 return 0;
349 }
350
351 inline void Tracer::setTraceComponents(const String& traceComponents)
352 {
353 // empty function
354 }
355
|
356 karl 1.25 #endif /* PEGASUS_REMOVE_TRACE */
357
358 //==============================================================================
359 //
360 // Tracing macros
361 //
362 //==============================================================================
363
364 // Defines a variable that bypasses inclusion of line and filename in output.
365 // #define PEGASUS_NO_FILE_LINE_TRACE=1 to exclude file names and line numbers
366 #ifdef PEGASUS_NO_FILE_LINE_TRACE
367 # define PEGASUS_COMMA_FILE_LINE /* empty */
368 # define PEGASUS_FILE_LINE_COMMA /* empty */
|
369 mike 1.2 #else
|
370 karl 1.25 # define PEGASUS_COMMA_FILE_LINE ,__FILE__,__LINE__
371 # define PEGASUS_FILE_LINE_COMMA __FILE__,__LINE__,
372 #endif
373
374 #ifdef PEGASUS_REMOVE_TRACE
375
376 # define PEG_METHOD_ENTER(comp,meth)
377 # define PEG_METHOD_EXIT()
378 # define PEG_TRACE_STRING(comp,level,string)
379 # define PEG_TRACE(VAR_ARGS)
|
380 marek 1.28 # define PEG_TRACE_CSTRING(comp,level,chars)
|
381 karl 1.25
382 #else /* PEGASUS_REMOVE_TRACE */
383
384 # define PEG_METHOD_ENTER(comp, meth) \
385 TracerToken __tracerToken; \
|
386 dave.sudlik 1.32 __tracerToken.method = 0; \
|
387 marek 1.28 do \
388 { \
389 if (Tracer::isTraceOn()) \
|
390 kumpf 1.29 Tracer::traceEnter( \
391 __tracerToken PEGASUS_COMMA_FILE_LINE, comp, meth); \
|
392 marek 1.28 } \
393 while (0)
|
394 karl 1.25
395 # define PEG_METHOD_EXIT() \
|
396 marek 1.28 do \
397 { \
398 if (Tracer::isTraceOn()) \
399 Tracer::traceExit(__tracerToken PEGASUS_COMMA_FILE_LINE); \
400 } \
401 while (0)
|
402 karl 1.25
403 // Macro for Trace String. the do construct allows this to appear
404 // as a single statement.
405 # define PEG_TRACE_STRING(comp, level, string) \
406 do \
407 { \
|
408 marek 1.28 if (Tracer::isTraceOn()) \
|
409 marek 1.31 { \
410 PEGASUS_ASSERT(level != Tracer::LEVEL1); \
411 if (Tracer::isTraceEnabled(comp, level)) \
412 { \
413 Tracer::traceCString(PEGASUS_FILE_LINE_COMMA \
414 comp, \
415 (const char*) (string).getCString()); \
416 } \
417 } \
|
418 marek 1.28 } \
419 while (0)
420
421 // Macro to trace character lists. the do construct allows this to appear
422 // as a single statement.
423 # define PEG_TRACE_CSTRING(comp, level, chars) \
424 do \
425 { \
426 if (Tracer::isTraceOn()) \
|
427 marek 1.31 { \
428 PEGASUS_ASSERT(level != Tracer::LEVEL1); \
429 if (Tracer::isTraceEnabled(comp, level)) \
430 { \
431 Tracer::traceCString(PEGASUS_FILE_LINE_COMMA comp, chars); \
432 } \
433 } \
|
434 karl 1.25 } \
435 while (0)
436
|
437 marek 1.31 //
438 // This class is constructed with the same arguments passed to PEG_TRACE().
439 // The constructor saves all the fixed arguments and calls va_start() on
440 // the varying arguments (wherein the va_list argument is the ap member of
441 // this class). The PEG_TRACE() macro eventually calls invoke() with the
442 // file and line macros in order to write the trace entry. For more details,
443 // see the comments below on the PEG_TRACE() macro.
444 //
445 class TraceCallFrame
446 {
447 public:
448
449 const char* file;
450 Uint32 line;
451
452 TraceCallFrame(const char* file_, Uint32 line_) : file(file_), line(line_)
453 {
454 }
455
456 PEGASUS_FORMAT(4, 5)
457 inline void invoke(
458 marek 1.31 const Uint32 component,
459 const Uint32 level,
460 const char* format,
461 ...)
462 {
463 if (Tracer::isTraceEnabled(component, level))
464 {
465 va_list ap;
466 va_start(ap, format);
467 Tracer::_trace(file, line, component, format, ap);
468 va_end(ap);
469 }
470 }
471
472 ~TraceCallFrame()
473 {
474 }
475 };
476 //
477 // This macro is a wrapper for calling the printf-style form of the
478 // Tracer::trace() function. Since macros cannot have a varying number of
479 marek 1.31 // arguments, PEG_TRACE() must be invoked with double parentheses. For
480 // example:
481 //
482 // PEG_TRACE((TRC_HTTP, Tracer::LEVEL1, "Oops: %d", 999));
483 //
484 // This macro offers two advantages over the calling trace() directly.
485 //
486 // 1. It eliminates the call to trace() if isTraceOn() returns false.
487 // This has proven to reduce the expense of servicing a request
488 // (when tracing is off) by as much as 3%.
489 //
490 // 2. It implicitly injects the __FILE__ and __LINE__ macros, relieving
491 // the caller of this burden.
492 //
|
493 karl 1.25 # define PEG_TRACE(VAR_ARGS) \
494 do \
495 { \
|
496 kumpf 1.27 if (Tracer::isTraceOn()) \
|
497 marek 1.31 { \
498 TraceCallFrame frame(__FILE__, __LINE__); \
499 frame.invoke VAR_ARGS; \
500 } \
|
501 karl 1.25 } \
502 while (0)
|
503 mike 1.22
|
504 karl 1.25 #endif /* !PEGASUS_REMOVE_TRACE */
|
505 mike 1.2
506 PEGASUS_NAMESPACE_END
507
508 #endif /* Pegasus_Tracer_h */
|
Return to
Tracer.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Common