Chapter 8. Starting and Stopping Log Central

To use Log Central, you need to start a Central Collector on your central host and start the agents on the managed nodes.

This chapter discusses the following topics:

The procedures for starting Log Central described in this chapter assume that you have completed the initial configuration steps discussed in Chapter 2, "Getting Started."

Starting the Log Central Data Collection System

The procedure for starting Log Central follows:

  1. Run the start_messaging command on the central host to start the Central Collector.

    After starting the Central Collector, the start_messaging process continues to run and acts as the server of the host and filter configuration to the start_messaging process on managed nodes. The start_messaging command also starts the Process Monitor (the proc_monitor process). The Process Monitor monitors the start_messaging process to ensure that it continues to run and restarts it if it dies. The start_messaging process in turn monitors the proc_monitor process and restarts it if it dies.

    Because Log Central processes on the central host provide Log Central agents with their configuration information when they are started, the Central Collector must be started before any of the data collection agents are started

    This is described under "Starting Log Central on a Central Host."

    Note: If you are using a backup Central Collector, start it at this time also.

  2. On each managed node, use the start_messaging command to start the Message Sender and Process Monitor.

    This is described under "Starting Log Central on the Managed Nodes."

  3. On each managed node, start a Log Monitor process for each log resource that you wish to manage.

    This is described under "Starting Log Monitor."

Starting Log Central on a Central Host

The start_messaging command starts Log Central components on the central host. The minimum set of components started by the start_messaging command on the central host are:

To use the start_messaging command on the central host, enter the following command: 

start_messaging [-f config_file] [-q] [-v] [-h] [central_host]
[backup_central_host]

where:

-f config_file
Uses config_file as the Log Central configuration file in place of the default (install_dir/etc/messaging.conf).

-q
Makes the process "quiet"; that is, no informational messages are displayed.

-v
Specifies the verbose option, which displays informational and debug messages.

-h
Prints out detailed usage information.

central_host
Specifies the host name of the machine acting as the primary central host. If not specified, the current host is considered to be the central host. This parameter must be specified when starting the Log Central system on the backup host or a managed node.

backup_central_host
Specifies the host name of the machine where the backup Central Collector is running. Data collection agents connect to the backup Central Collector if the Central Host cannot be reached.

Note: You need to specify a backup central host with the start_messaging command only if you are starting a data collection agent on the central host in addition to a Central Collector.

Because Log Central processes on the central host provide Log Central agents with their configuration information when they are started, the Central Collector must be started before any of the data collection agents are started.

After being invoked, the start_messaging process continues to run and can be used to stop the Central Collector (and other central host Log Central processes) by invoking the stop_messaging command. Use of the stop_messaging command is described in "Stopping the Log Central Data Collection System."

The start_messaging process must be able to find the Log Central configuration file (messaging.conf). The default location of this file is:

The install_dir variable is the directory under which you installed Log Central.

If you want start_messaging to use a configuration file that does not reside in the default location, invoke start_messaging with the -f option to provide a path to the file.

When starting a backup Central Collector, you must specify the central_host parameter. It is not necessary to specify the central_host when starting the primary Central Collector because start_messaging assumes that the machine it is invoked on is the central host if this parameter is not specified.

Once the start_messaging process is started on the central host, changes made to the Log Central configuration file will not take effect until the next time the Log Central processes are started using the start_messaging command.

Starting Log Central on the Managed Nodes

A managed node is any machine remote from the Central Collector that has log resources that you want to monitor. To start the Log Central processes on a managed node, do the following:

  1. Start the Message Sender and Process Monitor by invoking the start_messaging command. The syntax for the start_messaging command, when used on a managed node, follows: 

    start_messaging [-q] [-v] [-h] [central_host
    [backup_central_host]]

    where:

    -q
    Makes the process "quiet"; that is, no informational messages are displayed.

    -v
    Specifies the verbose option, which displays informational and debug messages.

    -h
    Prints out detailed usage information.

    central_host
    Specifies the host name of the machine where the primary Central Collector is running. If not specified, the current host is assumed to be the central host.

    backup_central_host
    Specifies the host name of the machine where the backup Central Collector is running. Data collection agents connect to the backup Central Collector if the primary Central Collector cannot be reached.

    Note: You must have already invoked the start_messaging command on the central host.

  2. Start a Log Monitor process for each log resource that you want to monitor.

    This is described under "Starting Log Monitor."

    Note: You must invoke the start_messaging command on the managed node before starting the Log Monitor processes.

To start the Log Central subsystem on a managed node, you must supply the name of the central host to the start_messaging process. The start_messaging process on the managed node connects to the start_messaging process running on the central host, using the udp service defined by the environment variable BEA_LC_CONF_SERVICE. The start_messaging process on the managed node then downloads the local host's configuration. If BEA_LC_CONF_SERVICE is not defined, a service called lc_conf is used by default. The start_messaging process then starts the Log Central subsystem according to the configuration received from the central host.

Starting Log Monitor

You must start a Log Monitor process for each log that you want to monitor on a managed node. The Log Monitor reads the logs generated by the managed resource, such as a computer system, a BEA TUXEDO application, or a relational database system. Log Monitor maps the attributes in the managed resource log messages to attributes in Log Central messages. Messages are then placed in the Message Sender's queue for forwarding to the Central Collector.

You can instruct Log Monitor to map log messages to Log Central message format for forwarding to the Central Collector in three ways:

Starting Log Monitor with Predefined Mappings

Predefined mappings are available for integrating the following log resources into the Log Central system:

To invoke Log Monitor with a predefined mapping, use the following command: 

log_monitor -i filename -P predefined_mapping [ -t time ]
[ -p pattern ] [ -x pattern ] [ -e entityname ]

where:

-i filename
This option specifies the incoming message file to use. You can also use a dash (-i -) to specify standard input.

-P predefined_mapping
This option tells Log Monitor to use a built-in message format mapping. The argument can be any one of the following:

TUXEDO
LC
NTEVENTLOG
ORACLE

-t time
This option specifies the amount of time to wait between forwards. The default is one second (that is, 1). Use 0 to forward once and then stop.

-p pattern
This option instructs the program to forward only lines that match pattern, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

-x pattern
This option instructs the program not to forward lines that match pattern, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

-e entityname
This option specifies the entity name to be used by the log_monitor process to register to the proc_monitor process. The default value is log_monitor. All Log Monitors on one managed node must have unique entry names. If the log_monitor process is run as a daemon (with -t 0), then the entity name option is not used.

The -p option can be used to select only certain messages for forwarding. The -x option can be used to select messages to be dropped. For more information, refer to Chapter 4, "Integrating Logs into Log Central."

For details about the predefined mappings, refer to Appendix G, "Predefined Log Mapping."

Using the LC Predefined Mapping

Log Central processes create temporary log files, which exhibit a common log file format. Normally the contents of these files make their way into the Log Central database through normal operation of the system. There are two abnormal situations where you might need to use Log Monitor to recover the contents of these files:

These are the only situations where you would start Log Monitor with the LC mapping.

Starting Log Monitor with Mappings in a Configuration File

A configuration file is simply a list of Log Monitor filters, each on a separate line. A log message will be forwarded by the Log Monitor if it is selected by at least one of the filters in the configuration file.

For information on constructing mappings in a Log Monitor configuration file, refer to Chapter 4, "Integrating Logs into Log Central."

The syntax for invoking Log Monitor with a configuration file follows: 

log_monitor -f config_filename -i filename [-t time] [-c]
[-e entityname]

where:

-f config_filename
This option specifies the configuration file from which to read filters.

-i filename
This option specifies the incoming message file to use. You can also use a dash (-i -) to specify standard input.

-t time
This option specifies the amount of time to wait between forwards. The default is one second (that is, 1). Use 0 to forward once and then stop.

-c
This option applies the commands in the configuration file only up to the first match in the configuration file.

For examples, see Chapter 4, "Integrating Logs into Log Central."

-e entityname
This option specifies the entity name to be used by the log_monitor process to register to the proc_monitor process. The default value is log_monitor. All Log Monitors on one managed node must have unique entry names. If the log_monitor process is run as a daemon (with -t 0), then the entity name option is not used.

Starting Log Monitor with Mapping Specified on the Command Line

The syntax for invoking Log Monitor by specifying all options on the command line follows: 

log_monitor -i filename [-t time] [-M log_level] [-m subsystem] 
   [-d msgid] [-n function] [-u userID] [-o hostname] [-I processID]
   [-b body] [-D date] [-p pattern] [-x pattern] [-T transactionID]
   [-P predefined_mapping] [-e entityname] [-S]

where:

-i filename
This option specifies the incoming message file to use. You can also use a dash (-i -) to specify standard input.

-t time
This option specifies the amount of time to wait between forwards. The default is one second (that is, 1). Use 0 to forward once and then stop.

-M log_level
This option specifies the logging level to use in the message. Logging level is a single character that must be one of the following:

N-A normal message

V-A verbose message

D-A debug message

S-A special message

-m subsystem
This option specifies the subsystem name to use in the message. The default is none.

-d msgid
This option specifies the message ID to use in the message. The default is 1000.

-n function
This option specifies the function name to use in the message. The default is none.

-u userID
This option specifies the user ID to use in the message. The default is the current user (that is, the owner of the log_monitor process).

-o hostname
This option specifies the host name to use in the message. The default is the machine on which Log Monitor is running.

-I processID
This option specifies the process ID to use in the message. The default is the process ID of the daemon process invoked by the Log Monitor command.

-b body
This option specifies the body of the message.

-D date %f"format"
This option specifies the date to use in the message. For information on specifying the date format, see Chapter 4, "Integrating Logs into Log Central."

-p pattern
This option instructs the program to forward only lines that match pattern, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

-x pattern
This option instructs the program not to forward lines that match pattern, which may simply be a string or it may use special characters. These are defined in Chapter 4, "Integrating Logs into Log Central."

-T transactionID
This option specifies the transaction ID to use in the message. The default is 0.

-P predefined_mapping
This option tells Log Monitor to use a built-in message format mapping. The argument can be any one of the following:

TUXEDO
LC
NTEVENTLOG
ORACLE

-e entityname
This option specifies the entity name to be used by the log_monitor process to register to the proc_monitor process. The default value is log_monitor. All Log Monitors on one managed node must have unique entry names. If the log_monitor process is run as a daemon (with -t 0), then the entity name option is not used.

-S
This option specifies one or more separators to be used to calculate field values in the input message file for corresponding %F specifiers on a command line. (The %F format symbol is described in Chapter 4, "Integrating Logs into Log Central.")

If more than one separator is specified, all are used to count the fields. If a message starts with a separator, the text between the first and the second separator is counted as field number 1; fields are numbered starting with 1 (not 0). If a message does not start with a separator, the first field consists of the text up to the first separator.

For examples, see Chapter 4, "Integrating Logs into Log Central."

A number of these options refer to specific attributes in a Log Central log message, such as message ID or process ID. The Log Central message format is described in Appendix A, "Message Format."

For information on how to use these options to construct mappings, consult Chapter 4, "Integrating Logs into Log Central."

Stopping the Log Central Data Collection System

To stop the Log Central data collection system, you must issue the stop_messaging command on each node where Log Central components are running.

The syntax of the stop_messaging command follows: 

stop_messaging [-q] [-v] [-h]

where:

-q
Makes the process "quiet"; that is, no informational messages are displayed.

-v
Specifies the verbose option, which displays informational and debug messages.

-h
Prints out detailed usage information.

When Log Monitor starts, it registers with the proc_monitor process. This enables the stop_messaging process to stop the Log Monitor processes when you issue the stop_messaging command to shut down the Log Central system. No separate command is required to shut down the Log Monitor processes.

Displaying Log Central System Information

Log Central includes a command, show_config, that enables you to display the current state of your Log Central configuration file, compile the configuration file, or display Log Central shared memory information.

Depending upon the arguments or options you enter, the show_config command compiles the configuration file or dumps the Log Central shared memory information to stdout. You can use this command to see if all processes are up or what processes are no longer running and to check for other system maintenance indicators.

The syntax of the show_config command follows: 

show_config -c [-f config_file] | -g | -p | -d | -e entity_name [-h]

where:

-c
Check syntax errors in configuration file.

-f config_filename
This option specifies the name of the Log Central configuration file to use with the -c option. If this option is not specified, install_dir/etc/messaging.conf is taken as the default. The install_dir variable is the directory in which Log Central was installed.

-g
Dumps the Log Central global information from shared memory to stdout.

-p
Dumps the proc_monitor shared memory information about the processes being monitored to stdout.

-d
Dumps the whole Log Central shared memory to stdout. This option is equivalent to using both the -g and -p options.

-e entityname
This option specifies the entity name to be used by the log_monitor process to register to the proc_monitor process. The default value is log_monitor. All Log Monitors on one managed node must have unique entry names. If the log_monitor process is run as a daemon (with -t 0), then the entity name option is not used.

-h
Prints out detailed usage information.

Example

Before using your configuration file at run time, you may wish to check for syntax errors. To validate your configuration file, run the following command: 

show_config -c -f config_file

In the preceding command, if the -f option is not specified, the file install_dir/etc/messaging.conf is used by default.

The show_config command displays syntax errors to stdout, showing line and character position.

Note: Avoid the use of tabs in your configuration file because they can cause the character positions reported to be inaccurate.