Global Configuration

You can set the logging and Health Monitor options for the entire xMatters system using the Global Configuration page.

Note that the settings on the Global Configuration page apply to the main xMatters logs and Health Monitor. Individual components such as Nodes and Device Engines also have log settings to create and maintain separate log files. For more information about logging configuration levels, see Configuring Node Logging.

About the Health Monitor

The Health Monitor component is responsible for monitoring the community of nodes, generating Alerts when error conditions are detected, and taking corrective action where possible. Its functions can be categorized as follows:

The Health Monitor triggers an Alert when any of the following conditions are met:

The latter list is not comprehensive; for detailed information about the conditions under which Health Monitor messages are generated, see Health Monitor Messages.

Note: When a disconnected database or Node is reconnected, the Health Monitor sends a notification indicating the successful resolution.

The Health Monitor supports the following notification mechanisms:

The Health Monitor generates two types of messages: detailed and terse. Detailed messages are used for emails sent by the Health Monitor, and terse messages are used when sending a notification to non-email text Devices. All detailed messages are also included in the xMatters log files.

Note: The Health Monitor generates two messages for inter-node communication errors: one message that includes the entire stack trace, and one that includes a simplified (terse) message. You can eliminate the stack trace message by opening the hmApplicationContext.xml file (located at node/assets/resources/spring/integration) in a text editor and setting notifyNodeCommunicationExceptions to "false". After making the change, restart the node.
To set Global Configuration settings:
  1. On the Global Configuration page, use the descriptions of the fields provided in the tables below to specify the required information.
  2. Click Save to apply your changes.
Log Settings
Setting Description

Maximum File Size

Maximum allowable file size for each log file. When this limit is reached, xMatters archives the log file and creates a new one.

Note that if the Number of Backups is set to “0”, xMatters discards the log file, and creates a new one.

Number of Backups

Maximum number of the most recent log files to retain. If the maximum number of backups is reached, xMatters deletes the oldest log files first.

Log Level

Default level of logging for components in the xMatters system. Individual component log settings override this parameter.

Note that more detailed log levels produce log files that cover a smaller window of time, determined by the maximum file size and the maximum number of backups.

Compression

Specifies the level of compression to use when creating archived log files. Possible values are:

  • None: Archived log files are not compressed.
  • Zip: Archived log files are compressed using a ZIP file format.
  • Gzip: Archived log files are compresed using the GNU zip format.

Note that not all operating systems support both archive types; check your deployment before selecting a compression type.

Health Monitor Settings
Setting Description

Mail Host

Name of the mail host to use for email messages generated by the Health Monitor.

Mail Port

Port number to use for the Health Monitor mail.

Mail Sender

Email address that appears in the “From” field of the notification email message.

Mail Recipient

Email address of the default Health Monitor mail recipient.

Notification Target

If available, the user name of the Company Administrator the Health Monitor should attempt to notify via xMatters in the event of a system health event.

Integration Agent Heartbeat Failure Threshold Specifies how many consecutive "heartbeats" an Integration Agent can miss before the Health Monitor sends a warning message. The value must be between 1 and 9999; the default is 5.
Notification Processing
Setting Description

Notification Processing Timeout

Length of time, in minutes, that a notification can remain in a serviceable state before it is automatically delinked. The default setting is one hour.

Note that a live notification could remain serviceable but undispatched for several reasons. For example, if a live notification for WCTP is created but the only configured WCTP engine goes down for a period longer than the specified timeout, the notification will be delinked.

Specifying a value that is too short (e.g., five minutes)could result in notification delivery failure if the Device Engines cannot process the number of notifications quickly enough. If this happens, increase the Notification Processing Timeout setting, or increase the number of available threads on your affected Device Engines.

Service Provider Failover
Setting Description

Enable Notifications

Enables Health Monitor notifications for Service Provider failures.

Threshold

Number of failures per Check Period that must be met or exceeded to trigger a notification. To prevent the Health Monitor from sending any notifications, enter “0”.

Check Period

How often, in minutes, to check whether the conditions for provider failure have been met.

Suppression Period

Length of time, in minutes, to suppress notifications for a provider after an instance of provider failure. The next time that provider fails after the suppression period will generate another notification and restart the suppression period for that provider.

Bounced Mail Settings
Setting Description
xMatters uses the Bounced Mail Settings to respond to emails that are not related to a notification. xMatters sends a message using the Bounced Mail Settings to indicate that the email was invalid.
Mail Host Name of the mail host to use for email messages responding to invalid responses.

Mail Port

Port number to use for the invalid responses mail.

Mail Sender

Email address that appears in the “From” field of the “invalid response” notification email message.

Note: This email address must not be the same as the email account used to send notifications from an SMTP/POP Device Engine.

Node Network Monitor
Setting Description
Sample Frequency

Specifies how often in seconds node network application layer latency is measured. This setting is used by the Node Network Statistics Report and the Health Monitor. To minimize impact on system resources, set this parameter to a larger value. To increase resolution when diagnosing node network communication issues, set this parameter to a smaller value.

Default=30, Min=30, Max=300

Aggregation Period

Specifies how often in minutes node network application layer latency and network drop statistics are calculated from the data collected. Latency data is averaged, and network drops are totalled. This setting is used by the Node Network Statistics Report and the Health Monitor. To minimize impact on system resources, set this parameter to a larger value. To increase resolution when diagnosing node network communication issues, set this parameter to a smaller value.

Default=5, Min=5, Max=30

Round Trip Threshold

Specifies the acceptable maximum duration in milliseconds for a round-trip communication between two nodes during the Aggregation Period. This setting is used by the Node Network Statistics Report and the Health Monitor; an alert is sent when this threshold is exceeded.

Default=300, Min=50, Max=1000

Network Drop Threshold

Specifies the acceptable maximum number of dropped connections between nodes that can occur during the specified Aggregation Period. This setting is used by the Node Network Statistics Report and the Health Monitor; an alert is sent when this threshold is exceeded.

Default=1, Min=0, Max=5

SMS Response Validation Settings
Setting Description
Enable SMS Response Validation

When enabled, xMatters will validate that each incoming SMS response using a text phone protocol is from an authorized xMatters User. This option must be selected to enable the remaining SMS Response Validation Settings.

SMS Validation Pattern

Specifies the validation pattern to use when validating incoming SMS responses. This pattern uses regular expressions to define how xMatters should recognize incoming SMS text phone numbers and compare them to the Device numbers stored in xMatters.

The pattern must contain one or more groups, defined by parentheses. For more information and examples, see "Specifying SMS validation patterns and templates".

SMS Validation Template

Specifies the validation template to use when validating incoming SMS responses. The template must contain one or more instances of "$n", where n is a digit corresponding to a groups defined in the pattern. For more information and examples, see "Specifying SMS validation patterns and templates".

Enable SMS Simple Responses

Indicates whether you want xMatters to accept simple SMS responses to notifications. These simple replies require Users to enter only a single digit as a response to a notification, rather than entering a phrase that includes the notification key.

xMatters replies to invalid response messages with the message "<response choice> is not a valid response."

For more information and examples, see Configuring simple SMS replies.

Specifying SMS validation patterns and templates

The SMS Validation Pattern and SMS Validation Template fields define how xMatters should compare the text phone Device numbers stored in xMatters with the text phone Device numbers returned by the Protocol Provider with an incoming response.

xMatters stores all text phone Device phone numbers as a string of digits only, with no parentheses, symbols, or spaces allowed, along with a country code appropriate to the Device. An incoming response from a provider may be formatted differently, and include a country code, special characters, or spaces (e.g., +44 (555) 123-4567)

The SMS Validation Pattern and SMS Validation Template Fields can be used to remove white spaces, special characters and any groups of numbers from an incoming phone number that are not part of the country code, area code, and phone number. Groups of characters must be delimited by a white space or special character, or be of a known number of digits.

You can use the following examples as a guideline for specifying your validation pattern and template. In each of the examples, the Device's phone number is stored in xMatters as "5551234567" with a country code of 44.

Note: If the validation pattern or template is not configured correctly, xMatters will ignore the responses. To check whether responses are being ignored, review the application server and notification server logs.
Example One
Example Two
Example Three

The following example illustrates how to specify the validation pattern and template for deployments using Clickatell: