Name

svcroute − Routing control file for DCE serviceability messages

Description

The file svc/routing specifies routing for serviceability messages.  The default location for svc/routing is the DCE local data directory (typically /opt/dcelocal/var).  The environment variable DCE_SVC_ROUTING_FILE, if set, specifies a different location for the file. 

The file consists of a series of text lines.  Blank lines and lines that begin with a # (number sign) character are ignored when the file’s contents are interpreted.  All other lines must consist of either three or four fields, each separated by a : (colon).  Leading whitespace is ignored. 

Lines consisting of three fields specify routing for nondebug serviceability messages.  Their format is as follows:
sev:out_form:dest[;out_form:dest . . . ] [GOESTO:{sev | comp}]

The sev (severity) field specifies one of the following message severities:

FATALFatal error exit: An unrecoverable error (such as database corruption) has occurred and will probably require manual intervention to be corrected.  The program usually terminates immediately after such an error. 

ERRORError detected: An unexpected event that is nonterminal (such as a timeout), or is correctable by human intervention, has occurred.  The program will continue operation, although some functions or services may no longer be available.  This severity level may also be used to indicate that a particular request or action could not be completed. 

WARNINGCorrectible error: An error occurred that was automatically corrected (for example, a configuration file was not found, and default values were used instead).  This severity level may also be used to indicate a condition that may be an error if the effects are undesirable (for example, removing all files as a side-effect of removing a nonempty directory).  This severity level may also be used to indicate a condition that, if not corrected, will eventually result in an error (for example, a printer’s running low on paper). 

NOTICEInformational notice: A significant routine major event has occurred; for example, a server has started. 

NOTICE_VERBOSE
Verbose information notice: A significant routine event has occurred; for example, a directory entry was removed.

The out_form (output form) field specifies how the messages of a given severity level should be processed, and must be one of the following:

BINFILEWrite these messages as a binary log entry to the specified file. 

TEXTFILEWrite these messages as human-readable text. 

FILEEquivalent to TEXTFILE. 

DISCARDDo not record messages of this severity level. 

STDOUTWrite these messages as human-readable text to standard output. 

STDERRWrite these messages as human-readable text to standard error. 

Files written as BINFILEs can be read and manipulated with a set of log file functions (for more information, see dce_svc_log_open() and dce_svc_log_get()), or by the svcdumplog command (see svcdumplog(1dce)). 

The out_form specifier may be followed by a two-number specifier of the form
.gens.count

where

gensis an integer that specifies the number of files (that is, generations) that should be kept

countis an integer specifying how many entries (that is, messages) should be written to each file

The multiple files are named by appending a dot to the simple specified name, dest, followed by the current generation number.  When the number of entries in a file reaches the maximum specified by count, the file is closed, the generation number is incremented, and the next file is opened.  When the maximum generation number files have been created and filled, the generation number is reset to 1, and a new file with that number is created and written to (thus overwriting the already-existing file with the same name), and so on, as long as messages are being written.  Thus the files wrap around to their beginning, and the total number of log files never exceeds gens, although messages continue to be written as long as the program continues writing them.  Note that when a program starts, the generation starts at 1. 

The dest (destination) field specifies where the message should be sent, and is a pathname.  The field can be left blank if the out_form specified is DISCARD, STDOUT, or STDERR.  The field can also contain a %ld string in the filename which, when the file is written, will be replaced by the process ID of the program that wrote the message(s).  Filenames may not contain colons or periods. 

Multiple routings for the same severity level can be specified by simply adding the additional desired routings as semicolon-separated out_form:dest strings. 

For example, the following strings specify that

       •Fatal error messages should be sent to the console. 

       •Warnings should be discarded. 

       •Notices should be written both to standard error and as binary entries in files located in the /tmp directory.  No more than 50 files should be written, and there should be no more than 100 messages written to each file.  The files will have names of the form /tmp/logprocess_id.n, where process_id is the process ID of the program originating the messages, and n is the generation number of the file (expressed with only as many digits as needed). 

FATAL:TEXTFILE:/dev/console
WARNING:DISCARD:--
NOTICE:STDERR:-;BINFILE.50.100:/tmp/log%ld

The GOESTO specifier allows messages for the severity whose routing specification it appears in to be routed to the same destination (and in the same output form) as those for the other, specified, severity level (or component name).  For example, the following specification means that WARNING messges should show up in three places: twice to stderr, and then once to the file /tmp/foo:

WARNING:STDERR:;GOESTO:FATAL
FATAL:STDERR:;FILE:/tmp/foo

Note that a GOESTO specification should be the last element in a multidestination route specification. 

Routing Serviceability Messages by Environment Variable

Serviceability message routing can also be specified by the values of certain environment variables.  If environment variables are used, the routings they specify will override any conflicting routes specified by the routing file. 

The routes are specified on the basis of severity level by putting the desired routing instructions in their corresponding environment variables:

       •SVC_FATAL

       •SVC_ERROR

       •SVC_WARNING

       •SVC_NOTICE

       •SVC_NOTICE_VERBOSE

Each variable should contain a single string in the format
out_form:dest[;out_form:dest . . . ]

where out_form and dest have the same meanings and form as in the preceding syntax line.  Multiple routings can be specified with semicolon-separated additional substrings specifying the additional routes, as shown. 

Setting Serviceability Debug Message Levels

Nine serviceability debug message levels (specified respectively by single digits from 1 to 9) are available.  The precise meaning of each level varies with the application or DCE component in question, but the general notion is that ascending to a higher level (for example, from 2 to 3) increases the level of informational detail in the messages. 

Setting debug messaging at a certain level means that all levels up to and including the specified level are enabled.  For example, if the debug level is set at 4, then the 1, 2, and 3 levels are enabled as well. 

The general format for the debug level specifier string is
component:sub_comp.level,sub_comp.level,. . .

where

componentis the three-character serviceability component code for the program whose debug message levels are being specified. 

sub_comp.level
is a serviceability subcomponent name, followed (after a dot) by a debug level (expressed as a single digit from 1 to 9).  Note that multiple subcomponent/level pairs can be specified in the string.

If there are multiple subcomponents and it is desired to set the debug level to be the same for all of them, then the following form will do this (where ∗ specifies all subcomponents):
component:∗.level

Routing Serviceability Debug Messages

Routing for serviceability debug messages can be specified in either of the two following ways:

       •By the contents of the SVC_COMP_DBG environment variable (where COMP is the code of the component, converted to upper case, whose debug message routing is to be set). 

       •By the contents of the /svc/routing routing file. 

The routing is specified by the contents of a specially-formatted string that is either included in the value of the environment variable or the contents of the routing file. 

The general format for the debug routing specifier string is
component:sub_comp.level,. . .:out_form:dest[;out_form:dest . . . ] \
[GOESTO:{sev | component}]

where component, sub_comp.level, out_form, dest, and sev have the same meanings as defined earlier in this reference page. 

For example, consider the following string value:

hel:∗.4:STDERR:-;TEXTFILE:/tmp/hel_debug_log_%ld

This value, when assigned to the SVC_HEL_DBG environment variable, would set the debug level and routing for all hel subcomponents.  A debug level of 4 is specified, and all debug messages of that level or lower will be written both to standard error, and in text form to the file /tmp/hel_debug_log_process_ID, where process_ID is the process ID of the program writing the messages.