JANUS TRACE

<section begin="desc" />Set Janus TRACE level<section end="desc" />

This command sets or overrides the trace settings for the named Janus port(s), determining which, and how much, information is written to the Model 204 journal.

You specify a bit mask integer setting that sums the values of the tracing options you want to invoke. The trace setting for a port is initially set to the value specified for the TRACE parameter on the JANUS DEFINE command for the port. The JANUS TRACE command will override this.

Syntax

<section begin="syntax" /> JANUS TRACE portname [ ipaddr | ipsubnet ] value | OFF <section end="syntax" />

Syntax terms

portname	The name of the port(s) to modify.
ipaddr	The remote IP address for which to set trace options. The IP address should be specified in standard dotted form: for example, 198.242.244.97. A host name cannot be specified on the JANUS TRACE command. If neither ipaddr nor ipsubnet is specified, the JANUS TRACE command is assumed to apply to all connections on the port.
ipsubnet	The IP subnet for which to set trace options. The IP subnet can be specified either in the standard dotted subnet and mask form, for example, 198.242.244.0/255.255.255.0, or a dotted IP address followed by the number of subnet bits, as in 198.242.244.0-24. All bits that are not part of the subnet must be 0. If neither ipaddr nor ipsubnet is specified, the JANUS TRACE command is assumed to apply to all connections on the port.
value	The bit-mask integer value to use for tracing the indicated connections. See the following page.
OFF	Indicates that no TRACE override is to be used for the specified IP address or addresses.

Usage notes

• JANUS TRACE does not affect the TRACE setting on the port definition, although it may override it. If a JANUS TRACE override is subsequently turned off, any JANUS DEFINE TRACE setting for the port becomes in effect again.
• JANUS TRACE may be issued while an online is running, and the order in which JANUS TRACE commands are specified is irrelevant. The JANUS TRACE command to be associated with a particular connection is the one that matches the IP address and has the most subnet bits. If a JANUS TRACE command exactly matches the IP address, it will always be used. If no IP address-specific rule is found, the subnet command with the most matching bits will be used. For example, a JANUS TRACE command for 198.242.244.96-27 will be used ahead of 198.242.244.0-24 for address 198.242.244.99, because the former subnet has 27 bits versus 24 for the second. If two subnet-based JANUS TRACE commands with exactly the same number of subnet bits match an IP address, it is unpredictable which command will apply. Fortunately, this can only happen if at least one of the subnet masks has holes (interspersed 0 and 1 bits) in it. This type of subnet is non-standard and highly unusual. If no JANUS TRACE commands match the IP address for a connection, the trace setting for the port will be the setting of the TRACE parameter on the port definition.
• In the following example, all connections for all ports starting with the character string WEB have tracing turned off, unless they match an IP address or subnet-specific JANUS TRACE command for the port to which they are connected:

  JANUS TRACE WEB* 0

  In the following example, connections from IP address 193.147.133.167 to port WEB204 will use a trace value of 7:

  JANUS TRACE WEB204 193.147.133.167 7

  In the following example, the special TRACE value for IP address 193.147.133.167 on port WEB204 is eliminated. Subsequent connections from this IP address will use the trace settings on the next most exactly matching JANUS TRACE command or, if there are none, the trace setting on the port definition.

  JANUS TRACE WEB204 193.147.133.167 OFF

  
  

  In the following example, the general override of the trace setting for port WEB204 is eliminated. The trace settings used for a connection that doesn't match any IP address or subnet-specific JANUS TRACE command will be the settings from the port definition.

  JANUS TRACE WEB204 OFF

• The TRACE setting controls the quantity of trace information logged to the audit trail. You specify an integer that sums the values of the options you want to have logged:

  1	Log the SQL request on SDS or URL rules processing on WEBSERV ports. This bit is useful on WEBSERV ports if there is confusion about which JANUS WEB rules apply to a particular URL.
  2	Log RPC requests on OPENSERV ports. Show request headers on WEBSERV ports.
  4	Log generated User Language (SDS ports only). Show form data on WEBSERV ports. This bit has no effect on OPENSERV ports. Using this bit on SDS ports can generate huge quantities of data so use it sparingly.
  8	Log in hex and char all activity on port (this allows TCP/IP level tracing).
  16	Log Persistent Client State (cookies) on WEBSERV ports.
  32	Trace web response headers.
  64	Trace web response text.
  128	Trace data between TCP and SSL.

  The default for TRACE is 3 for SDS and OPENSERV ports, and it is 0 for WEBSERV ports and all others.

  Setting the 8 bit may result in huge quantities of data going to the audit trail; this trace option logs RK lines of the form:

  AP?: offxxx : xdxdxdxd ... | ccc...ccc |

  where:

  ?	is I for input trace data, O for output, and U for urgent input data. For tracing Janus Sockets client connections (CLSOCK ports), after the I/O/U indicator will be the user's socket number in parentheses. For example, if an application has used the $SOCK_CONN function once and that port is being traced, it is socket number two, so the trace of $SOCK_SEND values will start with APO(2).
  offxxx	is the hex offset in the current stream.
  xdxdxdxd	is the hex representation of the data separated into 4 byte (8 digit) pieces.
  cccc	is the character representation of the data with non-printable characters changed to periods.

  Both input and output are traced when the JANUS DEFINE for the port has TRACE 8 specified.

• The current JANUS TRACE command settings for any or all ports can be determined with the JANUS DISPLAYTRACE command.

The TRACE keyword was introduced in Version 6.0 of the Sirius Mods. Before that, trace operations were controlled by the DEBUG keyword, which is no longer supported as of Version 6.5.

References

See List of Janus commands