Sending email alerts using Cognos TM1 Operations Console and Logback

Content

Before performing these steps, you must be familiar with the Logback utility. Logback is an open source utility, not an IBM product. For information about this utility, search the Internet for Logback documentation. For example, see http://logback.qos.ch/manual/index.html.

You can send email alerts based on server and process activity using Logback.

You can log events and generate email alerts in two ways:

1. You can generate email alerts for server activity. When a server goes online or offline, TM1 automatically generates an event. You can decide whether you want to email alerts or not for these events using filters in the Logback configuration file. You can also set up email alerts for other server activity, such as when the number of threads reaches a threshold.

To generate these types of alerts, follow these steps:

1. Configure Tomcat
2. Set up the Logback configuration file
3. Set up filters

2. You can generate emails for events logged by Watchdog. In this case, you create Watchdog rules to specify what events to capture, and then use the Logback configuration file to set up email alerts. For example, you can create a Watchdog rule to log an event when a certain process runs, and then configure Logback to send email alerts when Watchdog events occur.

To generate these types of alerts, follow these steps:

1. Configure Tomcat
2. Set up Watchdog
3. Set up the Logback configuration file

Configuring Tomcat for Logback
Before you can use Logback to send email alerts, you need to configure Tomcat with the location of the Logback configuration file, logback.xml.

Before you begin

Stop the TM1 Application Server.

Procedure

1. Start the Tomcat monitor:

a. Open a command prompt.

b. Go to the directory where Tomcat is installed, for example c:\Program Files\IBM\Cognos\tm1_64\tomcat\bin.

c. Run the following command: tomcat6w //ES//pmpsvc

2. On the Java tab, under Java Options, set Dlogback.configurationFile to [full_path]\logback.xml. For example, C:\logs\logback.xml.

3. Restart Tomcat. On the General tab, click Stop. After the Tomcat service has stopped, click Start.

4. Click OK.

5. If you are logging events with Watchdog, restart Watchdog for the servers you want to monitor.

Setting up the Logback configuration file

You can set two main types of alert:

• Server activity alerts:
• Status alerts: send an alert when the status of a server changes, for example when a server goes offline. You specify what servers and statuses to monitor using a TM1StatusFilter filter.
• Threshold alerts: send an alert when the number of threads, wait threads, or memory used reaches a threshold. You specify thresholds using a TM1ThresholdFilter filter.
• Watchdog alerts: send an email when a Watchdog event occurs

You set up alerts by configuring the logback.xml file. TM1 provides a sample file, which you can use as a starting point. The sample file is found in tm1_installation_location\bin64\opsconsoledata\logback-sample.xml.

Note: You must edit the logback-sample.xml file. It will not work as shipped.

Alert emails can contain information such as the message generated by Watchdog, a marker with a value such as NOTIFY_ADMIN, and an MDC value used to filter the output message. For TM1, you can use the following MDC keys:

MDCKEY_TM1SERVER = "tm1server"

MDCKEY_ADMINHOST = "adminhost"
MDCKEY_CURRENT = "current"
MDCKEY_LAST = "last"
MDCKEY_ALERTTYPE = "alert_type"

Alert type can be one of:

ALERTTYPE_STATUS = "status"

ALERTTYPE_THREADS = "threads"
ALERTTYPE_WAITTHREADS = "wait_threads"
ALERTTYPE_MEMORYUSED = "memory_used"

Before you begin

Before performing these steps, you must be familiar with the Logback utility. Logback is an open source utility, not an IBM product. For information about this utility, search the Internet for Logback documentation.

The steps in this section provide an overview.

Procedure

1. Open the sample logback.xml file: tm1_installation_location\tm1_64\bin64\opsconsoledata\logback-sample.xml.

2. Save the file with the name logback.xml in the location you specified in the Tomcat monitor, for example c:\logs\logback.xml.

3. Configure the FILE appender. In the <File> tag, specify the absolute path to the file you want to use for logging, for example c:\logs\sample-log.txt. This is the file that logs will be written to.

4. Configure the EMAIL appender. This appender configures how email alerts are sent.

a. Set the evaluator class: <evaluator class="com.ibm.tm1.logback.filters.PassEvaluator">

By default, Logback is configured to send emails only for the most serious error messages. Using the PassEvaluator configures Logback to send emails for less serious messages, such as memory usage, number of threads, and so on.

b. Configure the email options for your environment. For details, search the Internet for Logback documentation.

c. Configure the content to display in alert emails using the <layout> tag.

You can use MDC keys. For example, you can include the name of the TM1 server.

<pattern>%date - %message%n - %marker - %mdc{tm1server}</pattern>

5. If you want to send email alerts for server activity, specify the conditions that will trigger email alerts by configuring the ALERT appender. See "Setting up filters."

6. If you want to send email alerts for Watchdog events, configure the WATCHDOGTRAIL appender.

a. In the <File> tag, specify the absolute path to the file you want to use for logging Watchdog events, for example c:\Program Files\IBM\cognos\tm1_64\bin64\WatchdogActionTrail.log.

b. Specify a <logger> for Watchdog events. For more details about the <logger> tag, search the Internet for Logback documentation.

8. In the <root> tag, specify the logging level: DEBUG or ERROR and specify an <appender-ref>. For more details about the <appender-ref> tag, search the Internet for Logback documentation.

Setting up filters

You can specify the conditions under which email alerts should be sent by using filters. Use filter when you are setting up email alerts for server activity. Filters do not apply to Watchdog events.

It is a good practice to log to disk first, and then send email alerts when the filters are working in the way you need.

TM1 provides the following filters:

• TM1StatusFilter: Use this filter to set up server status alerts
• TM1ThresholdFilter: Use this filter to set up threshold alerts

For both status and threshold alerts, you can specify the servers and the admin host you want to monitor.

<tm1server>

This tag is optional. Specify the TM1 servers for which you want to receive email alerts. You can specify a list of TM1 servers. To receive email alerts for all TM1 servers, skip this tag.

<tm1server>Planning Sample</tm1server>

<tm1server>SData</tm1server>

<adminhost>

This tag is optional. Set the <adminhost> if you want to monitor all the servers on a particular admin host. Or, set it when you have identically named servers on two different admin hosts but want to monitor only one of them. Skip this tag if you want to monitor servers on all admin hosts.

<adminhost>adminhost 1</adminhost>

<adminhost>adminhost 2</adminhost>

TM1StatusFilter

The TM1StatusFilter sets the status values to display or suppress.

For a server, the valid values for <status> are:

• Online
• Running
• Starting
• Entering Bulk Load Mode
• Bulk Load Mode
• Offline
• Stopping

For a process, valid values include run, idle, busy, and so on.

The <status> tag can be in a list:

<status>running</status>

<status>offline</status>

<OnMatch> and <OnMisMatch>

Use OnMatch and OnMisMatch to filter on the servers for which you want alerts to be sent. For example, you can set up a filter that sends alerts for the Planning Sample server only.

You can chain filters together. For example, you can create a filter that sends alerts for all status changes on the Planning Sample server and no alerts for other servers.

OnMatch and OnMismatch both take the values ACCEPT, DENY, and NEUTRAL.

• ACCEPT: a log is created and processing does not pass to the next filter.
• DENY: a log is not created and processing does not pass to the next filter.
• NEUTRAL: it keeps going down the chain. If all filters return NEUTRAL, it will be logged.

In the sample Logback file, the last filter in the ALERT appender is DenyFilter. This filter always returns DENY. You can attach DenyFilter to the end of the list to make sure that, if all the other filters return NEUTRAL or if there is any doubt, you can get to the end of the filter list without logging anything.

<filter class="com.ibm.tm1.logback.filters.DenyFilter">
</filter>

Example status filters

This example logs all status changes for the server Planning Sample and no status changes for all other servers.

<filter class=”com.ibm.tm1.logging.TM1StatusFilter”>

<tm1server>Planning Sample</tm1server>
<OnMatch>ACCEPT</OnMatch>
<OnMismatch>DENY</OnMismatch>

</filter>

This example prevents logging for all servers when the status is running.

<filter class=”com.ibm.tm1.logging.TM1StatusFilter”>

<status>running</status>
<OnMatch>DENY</OnMatch>

</filter>

TM1ThresholdFilter

TM1ThresholdFilter handles the threads, wait_threads, and memory_used alert types.

<alerttype>

This tag specifies the type of event to which the filter applies. The allowed values are:

• threads
• wait_threads
• memory_used

You can have more than one alert type in a filter.

<alerttype>threads</alerttype>

<alerttype>wait_threads</alerttype>

<threshold>

This tag sets values for thresholds. Thresholds must be numeric. For the alert type memory_used, the value is in MB. Thresholds can be in a list, so you can have more than one threshold in a filter.

<threshold>50</threshold>

<threshold>100</threshold>

<direction>

The <direction> tag is optional. By default, an alert is created on both the up and down directions.

<direction>up</direction>

You can have two different filters in a chain but only one direction per filter. For example, you can have one filter for the up direction at 50 and another filter for the down direction at 40. This sends an alert when the threshold goes above 50 or below 40.

Threshold examples

This example logs messages when the memory usage for any server crosses the 256 MB boundary either up or down.

<filter class=”com.ibm.tm1.logging.TM1ThresholdFilter”>

<alerttype>memory_usage</alerttype>
<threshold>256</threshold>

</filter>

This example logs messages for the Planning Sample and SData servers when threads cross the 50 boundary going up and then again when they reach 100 and 150.

<filter class=”com.ibm.tm1.logging.TM1ThresholdFilter”>

<tm1server>Planning Sample</tm1server>
<tm1server>SData</tm1server>
<alerttype>threads</alerttype>
<threshold>50</threshold>
<threshold>100</threshold>
<threshold>150</threshold>
<direction>up</direction>

</filter>

Combining filters

This example causes alerts to be sent when the threads or wait threads go above 50 or below 40 for any server. Alerts will also be sent when the Planning Sample server changes status to anything except running.

<filter class=”com.ibm.tm1.logging.TM1ThresholdFilter”>

<alerttype>threads</alerttype>
<alerttype>wait_threads</alerttype>
<threshold>50</threshold>
<direction>up</direction>

</filter>
<filter class=”com.ibm.tm1.logging.TM1ThresholdFilter”>

<alerttype>threads</alerttype>
<alerttype>wait_threads</alerttype>
<threshold>40</threshold>
<direction>down</direction>

</filter>
<filter class=”com.ibm.tm1.logging.TM1StatusFilter”>

<status>running</status>
<OnMatch>DENY</OnMatch>

</filter>
<filter class=”com.ibm.tm1.logging.TM1StatusFilter”>

<tm1server>Planning Sample</tm1server>
<OnMatch>DENY</OnMatch>

</filter>
<filter class=”com.ibm.tm1.logging.DenyFilter”>
</filter>

Logback sample file

A Logback sample file is found in tm1_installation_location\tm1_64\bin64\opsconsoledata.

You must edit this file to use email alerts. It will not work as shipped.

Note: In the sample file, the root logging level is set to DEBUG. This can cause the log file size to grow very rapidly. If you do not need debug logging, set the root logging level to ERROR.

<root>

<level value="ERROR" />
<appender-ref ref="FILE" />

</root>