Server Logging Implementation

CIYAM application servers append to log files (for binary installations check the “/var/log/ciyam” directory) in order to provide information (such as when starting up or after shutting down or when certain scripts have been executed or if any unexpected errors occur) which can be useful for both developers and administrators.

Changing the Log Files Directory

The main application server log file is “ciyam_server.log” with “ciyam_script.log” being used for logging any applicable CIYAM protocol (or other more general) scripts that have been invoked by an application or through the automated scheduling sub-system.

The log file names may not be changed but the directory that they are located in can be changed by either use of the “<log_files_path>” attribute in the application server’s configuration file (i.e. ciyam_server.sio) or with the command line option “-log_dir=<directory>” (with the command line option always taking precedence).

The command line option is generally only intended for developers and is most useful when wanting to have two or more server instances running on the same machine (so each instance can have its own log files).

If no configuration or command line option was supplied then the server’s “current” directory will instead be used although this can still be effectively customised (and is for binary releases) by using soft-link files.

The system variable “@log_files_dir” can also be used in order to change this directory at runtime (note that this change will take almost immediate effect in “ciyam_server.log” and after any currently executing scripts have completed for “ciyam_script.log”). The initial log file directory (from either the configuration file or command line option if had been provided) will be restored if this system variable is cleared.

Checking Log File Content

Using a standard tool such as “tail” is generally the best way for an administrator to check log file content (e.g. tail /var/log/ciyam/ciyam_server.log) whereas developers might prefer to use the “log_tail” application protocol command (as it will automatically handle the correct log file directory and can be used if logged in as “admin” from the System Information “Settings” in the application web UI).

Application Server Tracing

The “ciyam_server.log” file by default will only contain a very minimal set of messages (such as for start up and shut down along with any unexpected errors) but through the use of “trace flags” the number and frequency of logging messages can be greatly increased.

Some care should be taken when choosing more detailed logging (and especially the “verbose” level) as the log file size can grow very rapidly (setting the “@log_files_dir” system variable to “/tmp” would be a suggestion to avoid blowing out the size of the “normal” log file when using the verbose log trace level).

The “trace flags” value is shown (and needs to be provided) as a hexadecimal value. The value consists of two parts that are a maximum of four nibbles in size with the first four containing the log “level” value and the second four holding the log “flags” value. All leading zero digits can be omitted but it should be noted that if the level is zero then no logging will occur at all. Use server configuration attribute “<trace_flags>” or the command line option “-trace=<flags>” (with the command line option always taking precedence). If no value is specified then the default is “10000” (which will result in only minimal general messages being logged).

The application protocol command “system_trace” (or simply “trace”) is available to get/set the “trace flags” value but in order to view the names and hex values of both flags and levels (and to allow setting them using names rather than values) further “system_trace” prefixed commands are as follows:

system_trace_flags
system_trace_level
system_trace_levels

> trace_level
minimal

> trace_flags
general

> trace
10000

To view all available trace flags use “trace_flags -list” and the command “trace_levels” will list all of the available trace levels. If wanting to view trace “details” of both “session” commands and RDBMS “queries” the following commands will perform this along with showing the actual “trace flags” value (if needing this value for either the configuration file or command line option).

> trace_level details

> trace_flags -set queries,session

> trace
7000c

There is also a “system_trace_message” command available to log a customised message (which is very useful if needing to debug an application protocol script).

As detailed (and especially verbose) tracing can result in very large amount of log file output there are two special server variables that can be set in order to limit this output. The first is “@trace_session_ids” and this can be used to set the specific session ids for tracing (very useful to target main peer sessions whilst skipping logging for support sessions).

> system_variable @trace_session_ids 1,3

Using a “+” or “-” prefix will add or remove a session id from the set of session ids that tracing will apply to (use just “+” or “-” to add/remove the current session).

> system_variable @trace_session_ids -3,+5

The second system variable is “@trace_filters” which is a set of strings which every trace message is checked to contain. If any one of the filter strings is found then the trace message will be omitted. This example is a simplistic filter to prevent any “session_list” and “system_variable” commands from being logged.

> system_variable @trace_filters session_list,system_variable

Finally some hard-coded constants and global variables are being used in order to prevent logging more than a fixed number of messages every few seconds (where a special “****** skipped excessive logging ******” message will appear in the log file to indicate that this has happened).