Adding a new message to a Logfile Adapters

One of the easiest ways of integrating your own applications into Tivoli is to use the logfile adapter. This tip looks at how to add new messages to the logfile adapters.

Formatting Messages

The logfile event adapter can match events in several different formats and as standard Tivoli supply several matched formats in the files

If the messages are being classified for an Adapter Configuration Profile the files must be edited in the$BINDIR/../generic_unix/TME/ACF_REP

For this tip I will add 2 new messages and I will take them from the $DBDIR/gatelog logfile created and used by a gateway.

The Messages

The messages are:

1998/09/10 12:09:49 +08: gateway boot: started booting.
1998/09/10 12:09:54 +08: gateway boot: gateway boot completed successfully.

The Classes

I will classify these two messages into the following three classes:

• Gateway_Booting
• Gateway_Booted
• Gateway_Boot_Base

The last class is used as a base class that the other two classes will be built from. This allows us to avoid declaring the same slots for both classes. If you look at Logfile_Base or NT_Base you will see that most of the syslog and Event Viewer messages follow form these two basic formats.

Matching the Messages to the Classes

The logfile adapter is able to map widely differing events using a scanf() or printf() type format. For example all error messages that are sent to the syslog daemon could be classified as:

%t %s %s*

or even

%s+

where

Obviously we do not want only one type of event and therefore by replacing strings with constants we can make each format map to a unique class.

e.g.

%t %s Error Message %s

or

%t %s login: ROOT LOGIN %s

Once each event can be classified into this format we can then map each event to a Class and each part of an event to slots.

Format of the .fmt file

Each format in the .fmt specification has four parts:

• The class is classified with the keywordFORMAT followed by the class name. This may be followed by a keyword called FOLLOWS that allows us to use mappings from a previously definedFORMAT.
• The format
• The slots
• The END keyword to denote the end of the classification.

e.g.

FORMAT Root_Login_Success FOLLOWS Root_Login
%t %s login: ROOT LOGIN %s
on_tty $3
msg PRINTF("root login %s", on_tty)
END

Therefore to create a base event from the messages

1998/09/10 12:09:49 +08: gateway boot: started booting.
1998/09/10 12:09:54 +08: gateway boot: gateway boot completed successfully.

we must first split the messages into its component parts and assign each part to a format.

The First Classification

The first classification will be theGateway_Boot_Base base event (we will always classify a base event unless the message can follow from an existing event).

IMPORTANT: Our classifications will be added at the BOTTOM of the .fmt file as the adapters read from the bottom to the top. Therefore the most generic formats such as NT_Base are at the top of the file.

Now we know the basics let’s go through the four parts of the first classification and fill in the details

• The class we are assigning the logfile message to is assigned with the keyword FORMAT followed by the class name, Gateway_Boot_Base.

e.g.

FORMAT Gateway_Boot_Base

(This may be followed by a keyword calledFOLLOWS that allows us to use mappings from a previously defined FORMAT but in this case we are defining the base event).

• The format is made up of the variable parts (e.g date, time or hostname) and also the fixed strings that make the message unique to the Gateway_Boot_Base event. In this case the date, time will always change each time the event is sent therefore they are assigned variables (%s or %t) however the fixed string: gateway boot: is unique for this type of event.

Therefore our format will be %s %s %s*: gateway boot: %s*

• The slots are mapped against the variable parts that have been matched against a %s, %s+, %s* or %t. The first map will be $1, the second $2 and so on. Fixed strings cannot be mapped into slots but can be set using PRINTF or just hard coding the string ( e.g. msg "hello" ).

hostname DEFAULT
date2 $1
time $2
-discard $3
-message $4
msg PRINTF("Gateway on %s %s",hostname, message)

Note 1:A slot in a .fmt file prefixed by a minus sign will not be passed as a slot to the TEC server.

e.g.

-date2 $3

Note 2: New values can be defined with the PRINTF keyword.

e.g.

msg PRINTF("This is a new message on", hostname)

• The END keyword denotes the end of the classification.

Therefore the first format will be:

FORMAT Gateway_Boot_Base
%s %s %s*: gateway boot: %s*
hostname DEFAULT
date2 $1
time $2
-discard $3
-message $4
msg PRINTF("Gateway on %s %s",hostname, message)
END

The Other Classifications

The next two classes Gateway_Booting andGateway_Booted are defined as followingGateway_Boot_Base because they can use some of the mappings that we have already defined.

This can be written as:

FORMAT Gateway_Booting FOLLOWS Gateway_Boot_Base
%s %s %s*: gateway boot: started booting
msg PRINTF("Gateway on %s is booting",hostname)
END

This can be written as:

FORMAT Gateway_Booted FOLLOWS Gateway_Boot_Base
%s %s %s*: gateway boot: gateway boot: completed successfully.
msg PRINTF("Gateway on %s has booted successfully ",hostname)
END

Added New Classes to the Baroc file

Now that we have defined our classes and slots we must create a baroc file so that the rulebase knows what events are due to arrive. There are two new slots that are not part of the EVENT class that we need to define in a new file called Gateway.baroc. We can define our class definitions to look like this.

TEC_CLASS : Gateway_Booting_Base ISA EVENT DEFINES { date2: STRING; time: STRING; source: default = "GATEWAY"; }; END TEC_CLASS : Gateway_Booting ISA Gateway_Booting_Base; END TEC_CLASS : Gateway_Booted ISA Gateway_Booting_Base; END

Note: We have not defined the slots that we are discarding in the .fmt file using the –slot syntax as they do get passed to the TEC.

The cds file

The format file that we have created should now work as expected however to allow the events to be matched correctly there is another file named tecad_logfile.cds (tecad_nt.cds on NT) that defines how an event adapter constructs events. For each event class the event adapter supports, one or more CDS or Class Definition Statements. These are defined to map incoming events to a class and also how the slots are to be filled. The file is derived from the fmt file and is created with eitherlogfile_gencds or nt_gencds. IT SHOULD NEVER BE EDITED.

To create a file use the syntax:

../bin/logfile_gencds tecad_logfile.fmt > tecad_logfile.cds

It is always worth running the command first without redirecting the output to the cds file to ensure that the output is valid and that there are no mistakes in the fmt file.

And Finally

Finally you must remember to add the name of the new logfile you are monitoring into the configuration file. This is done by adding the keyword LogSources to either the tecad_nt.conf or tecad_logfile.conf file directly or to the Environment section of the ACP profile.

e.g.

# Thu Jul 08 14:00:28 1999 # # tecad_logfile Configuration ServerLocation=@EventServer EventMaxSize=4096 BufEvtPath=/etc/Tivoli/tec/tecad_logfile.cache PollInterval=30 LogSources=/tivoli/db/scooby.db/gatelog # Filter:Class=Logfile_Base

Don’t forget to distribute.