svcroute(5dce)

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 white space 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:

FATAL
Fatal 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.

ERROR
Error 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.

WARNING
Correctable 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).

NOTICE
Informational 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:

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

TEXTFILE
Write these messages as human-readable text.

FILE
Equivalent to TEXTFILE.

DISCARD
Do not record messages of this severity level.

STDOUT
Write these messages as human-readable text to standard output.

STDERR
Write 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(3dce) and dce_svc_log_get(3dce)), or by the svcdumplog command.

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

&.gens.count

where

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

count
is 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 path name. 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).component (or message. For example, the following specification means that warning messages 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.

More:

Routing Serviceability Messages by Environment Variable

Setting Serviceability Debug Message Levels

Routing Serviceability Debug Messages