doc/html/trace.html
author Scott Ehlert <ds@alliedmods.net>
Thu Sep 26 17:00:32 2013 -0500 (2013-09-26)
changeset 284 ca90ccdb8d49
parent 0 d15304fcb7a7
permissions -rw-r--r--
Fixed makefile error when issuing 'make clean' or 'make distclean'.
darope@0
     1
<!-- vi: set ts=4 sw=4 : -->
darope@0
     2
<!-- vim: set tw=75 : -->
darope@0
     3
darope@0
     4
<HTML>
darope@0
     5
<head>
darope@0
     6
<title>Metamod TraceAPI Plugin</title>
darope@0
     7
</head>
darope@0
     8
<body>
darope@0
     9
darope@0
    10
<h1>TraceAPI plugin
darope@0
    11
</h1>
darope@0
    12
darope@0
    13
<p> This was originally intended as a (more or less) complete example of a
darope@0
    14
Metamod plugin.  It catches <b><i>every</i></b> call available to it (dll
darope@0
    15
routines both before and after the game, as well as engine functions both
darope@0
    16
before and after the engine).
darope@0
    17
darope@0
    18
<p> Because it catches every routine, I figured I'd give it the ability to
darope@0
    19
log when given routines are called, so it became an "api tracing" plugin.
darope@0
    20
:)
darope@0
    21
darope@0
    22
<p> This can actually be useful for tracking the operation of the HL
darope@0
    23
engine, as well as that of a particular HL game mod.
darope@0
    24
darope@0
    25
<p> It recognizes the following server cvars:
darope@0
    26
darope@0
    27
<p><pre>
darope@0
    28
   // Tracing debug levels; higher values log increasingly frequent routines.
darope@0
    29
   // Currently 0-50.  See "api_info.cpp" for the debug levels of various
darope@0
    30
   // functions.
darope@0
    31
darope@0
    32
   // Trace level for dllapi routines.
darope@0
    33
   trace_dllapi
darope@0
    34
darope@0
    35
   // Trace level for "new" dllapi routines.
darope@0
    36
   trace_newapi
darope@0
    37
darope@0
    38
   // Trace level for engine functions.
darope@0
    39
   trace_engine
darope@0
    40
darope@0
    41
   // Enable unlimited trace logging.  By default (as of v1.06), it only
darope@0
    42
   // logs _one_ trace message per second, to keep from overwhelming the
darope@0
    43
   // server.  Set to "1" to enable unlimited logging.  (Default "0")
darope@0
    44
   trace_unlimit
darope@0
    45
darope@0
    46
   // General debug level, independent of trace levels.  Not currently used.
darope@0
    47
   trace_debug
darope@0
    48
darope@0
    49
</pre>
darope@0
    50
darope@0
    51
<p> and the following server commands:
darope@0
    52
darope@0
    53
<p><pre>
darope@0
    54
   // Enable tracing of a given routine, independent of "trace_*" level.
darope@0
    55
   // See the list of routine names in "api_info.cpp".  Case is insignificant.
darope@0
    56
   trace set &lt;APIroutine&gt;
darope@0
    57
darope@0
    58
   // Disable tracing of a given routine, iff previously enabled with "trace".
darope@0
    59
   // Doesn't affect routines being logged via "trace_*" level.
darope@0
    60
   trace unset &lt;APIroutine&gt;
darope@0
    61
darope@0
    62
   // Show the routines being traced.
darope@0
    63
   trace show
darope@0
    64
darope@0
    65
   // List the various routines that can be traced.
darope@0
    66
   trace list dllapi
darope@0
    67
   trace list newapi
darope@0
    68
   trace list engine
darope@0
    69
   trace list all
darope@0
    70
darope@0
    71
   // Prints out version/date/etc.
darope@0
    72
   trace version
darope@0
    73
</pre>
darope@0
    74
darope@0
    75
<p> Note the information it logs on each routine invocation is, at the
darope@0
    76
moment, relatively minimal.  I included information that seemed obvious
darope@0
    77
(args for a <tt>ClientCommand</tt>, etc), and I've added info for other
darope@0
    78
routines as I've come across a need.  Most routines I still know too little
darope@0
    79
about to log any particular information (<tt>CreateBaseline</tt>, etc).
darope@0
    80
Feel free to add information that you're interested in to the log messages
darope@0
    81
in the routines; the examples should be pretty self-explanatory.  I'd be
darope@0
    82
interested in knowing as well, for adding it to the distribution code.
darope@0
    83
darope@0
    84
<p>
darope@0
    85
<hr>
darope@0
    86
darope@0
    87
</body>
darope@0
    88
</HTML>