|
|
|
|
|
The trace command outputs trace messages to standard output, while the system is taking calls, for specified processes and channels.
This information may be useful for debugging applications and DIPs.
Synopsis
trace [process_name]...[chan chan_range]...[card card#]...[area area_range][level level_range][date][nodate][lbolt][tracelog | startlog]...[sleep sleep_time]
Description
The trace command prints trace messages to the standard output device (stdout) according to specified options. Executing trace also causes trace output to be logged to the trace shared memory buffer or to the trace log.
When trace is specified with process_name, all process-specific trace messages from process_name are printed. Process-specific trace messages are printed regardless of which channels the specified process may own or on which processes are operating, unless the -a option is specified.
When trace is specified with chan or card options, all channel-specific messages, from any process are printed. The card option is applicable only to network interface cards (that is, cards that have channels). The card option is a special case of the channel option.
Note:
The process and channel/card arguments can work together using the -a option. For example, the command trace -a chan 0 level all area all TSM will print trace messages for the process TSM and channel 0.
If the -a option is not used, a combination of the process_name variable and chan options prints trace messages from both the process_name variable and chan options. These options act collectively rather than selectively.
If the -a option is used, a combination of the process_name variable and chan options prints trace messages that are logged in the process and are for the specified channels.
If area is specified, only the process or channel messages associated with area are printed. The area option is, therefore, selective. Areas may be integers ranging from 1 to 32. Areas 1 through 16 are available for user applications. The voice system reserves areas 17 through 32.
The trace area arguments are described in the following table:
Argument |
Description |
AS (area 17) |
Trace advanced service operations such as TTS and speech recognition |
EM (area 18) |
Trace event management operations |
IN (area 19) |
Trace caller input operations including touchtone and speech recognition |
PM (area 20) |
Trace parameter management operations |
RM (area 21) |
Trace resource management operations |
SE (area 22) |
Trace script execution. This includes trace entries made implicitly by Script Builder applications and through tas(1) scripts via the |
ST (area 23) |
Trace call and application initialization and completion operations |
TS (area 24) |
Trace telephony service operations |
VS (area 25) |
Trace voice code and play operations |
ER (area 26) |
Trace error processing operations |
IL (area 27) |
Trace internal library operations |
SI (area 28) |
Trace script instructions. Every TSM script instruction displays a trace message. |
AD (area 29) |
Trace administration operations |
BM (area 30) |
Trace bus management operations |
OT (area 32) |
Trace old trace instructions. All old trace messages are placed in this area. |
ALL (area 1-32) |
Trace all areas |
The default, if area is omitted, is all areas except SI (area 28). Trace areas may also be specified numerically with lists and ranges. For example, the following is legal:
trace chan 5 area 1-7,10,TS
A level argument may also be specified. Levels range from 1 through 32, where level 1 indicates the least amount of detail and level 32 indicates the greatest level of detail. Levels may be specified as a single number, comma-separated list, or ranges. The current internal voice system levels in use (levels 17 through 32) may be identified through mnemonics. A complete list of area and level mnemonics can be displayed by executing the trace command with no arguments. The current voice system levels (areas 1 through 32) are described in the following table:
Argument |
Description |
U (levels 1-16) |
Trace all user levels |
AE (level 17) |
Trace internal application error messages |
AG (level 18) |
Trace internal application general messages |
AX (level 19) |
Trace internal application enter/exit messages |
A (levels 17-19) |
Trace all internal application levels |
FE (level 20) |
Trace user-callable function error messages |
FG (level 21) |
Trace user-callable function general messages |
FX (level 22) |
Trace user-callable function enter/exit messages |
F (levels 20-22) |
Trace all user-callable function levels |
PE (level 23) |
Trace process interface function error messages |
PG (level 24) |
Trace process interface function general messages |
PX (level 25) |
Trace process interface function enter/exit messages |
P (levels 23-25) |
Trace all process interface function levels |
IE (level 26) |
Trace error processing operations |
IG (level 27) |
Trace internal library operations |
IX (level 28) |
Trace script instructions. Every TSM script instruction displays a trace message. |
I (levels 26-28) |
Trace script instructions. Every TSM script instruction is displayed. |
RH (level 29) |
Trace RM Helper function enter/exit messages |
RE (level 30) |
Trace RM Helper function error messages |
RG (level 31) |
Trace RM Helper function general messages |
RX (level 32) |
Trace RM function enter/exit messages |
R (levels 29-32) |
Trace all RM Helper and RM function messages |
S (level 17-32) |
Trace all IRAPI system levels |
ALL (levels 1-32) |
Trace all levels |
The default, if level is omitted, is levels U, A, AE, FE, PE, IE, and RE. Trace levels may also be specified numerically with lists and ranges.
If the tracelog option is specified, all trace messages are logged to the trace log file and sent to stdout. If startlog is specified, tracing is done to the trace log but no trace output is sent to stdout.
Trace messages may be printed with or without the date and time when they are generated. The date option is set by default and prints the date and time of trace messages. If the nodate option is specified, the date and time will not print. If the tracelog or startlog option is specified, the date and time are always printed for entries in the trace log file.
With the lbolt option, you can activate a counter that starts with 0 when the system boots, and is incremented every 1/100th of a second.
If the sleep argument is specified, trace sleeps sleep_time milliseconds between reading the trace buffer. The default is 200 milliseconds.
The trace stop command clears any active trace settings, ensuring that no trace output is generated to the trace log.
By default, all trace messages are saved in a trace shared memory buffer. The trace buffer is a circular buffer. If trace messages are written to the trace buffer faster than the trace command can read them, eventually the trace buffer overflows and trace messages are lost. When this happens, trace prints the message TRACE: ***** LOST XXX RECORDS , where XXX is the number of trace messages lost. Two ways to minimize the number of trace messages lost exists:
Use the sleep argument of the trace command to decrease the time that trace sleeps between reading the buffer (default sleep_time = 200 ms).
Increase the size of the trace buffer by adding or modifying the line TRACE_BUFFER_SIZE=X in the /vs/data/irAPI.rc file, where X is the number of messages that the trace buffer can hold (default = 40000). Increasing the value of X should reduce the chance of losing trace messages.
If you change the size of the trace buffer, you must stop and restart the voice system (stop_vs and start_vs). Otherwise, you are not able to run trace.
Files
Examples
Examples of valid level lists and ranges are shown in the following table:
Level list or range |
Description |
1,2 |
Trace levels at 1 and 2 |
1-4,FE |
Trace at levels 1, 2, 3, 4, and 20 |
all |
Trace at levels 1-32 |
Note:
Levels are not hierarchically inclusive. That is, level 3 does not imply that tracing at levels 1 and 2 also occurs, which could be achieved by using a range starting from 1. For example, 1-3 for levels 1, 2, and 3.
Note that a user input (touchtone and speech recognition) log can be implemented by the following trace command:
trace chan all area IN level F
