Custom Monitoring

Another exciting feature of IxoraRMS is the ability to add custom monitoring data providers and to integrate them seamlessly with the built-in agents.

A provider is the component which collects data from an external source and converts it into entities and counters. Providers are always associated with agents, from which they inherit configuration options, and to which they contribute counters.

The steps involved in creating a custom monitoring data provider are:

• Create an agent (optional). Using "Agent Installer" create a new custom agent which will host the new provider(s). The agent provides configuration common to all its providers and serves as a root for the entity tree.
• Create a provider for this agent. Using "Provider Manager", select the new agent (or an existing one) and add a new provider for it. Select one of provider types (Java, SQL or Process) and configure its running parameters and the structure of its entities and counters.
• Activate the new agent as you would any other agent, optionally enabling or disabling some providers.

Agent Installer

This dialog is accessible from "Tools" - "Agent Installer".

To add a new agent, click "Install". This brings out the "Agent Installation Type" dialog box as shown below.

Select the "Custom agent installation" entry from the drop down list and press "Ok". This opens the "Agent Template" dialog box as shown below.

Select the desired agent template and press "Ok".

The available agent templates are:

• Process - use this when monitoring data is extracted from external processes.
• Java - use this when monitoring data is extracted using a Java class.
• SQL - use this when data is extracted using SQL statements.
• JMX JSR 160 - use this when data is extracted via JMX from systems implementing the JSR 160 specification.

The next dialog is "Agent Installation Data".

The following fields are available on this dialog.

• Name: agent name, cannot be changed after creation.
• Description: agent description.
• Class: Java class containing agent implementation, manual editing not recommended, reserved for future use.
• Category: The name of the category which the agent belongs to. The predefined values are the following:
  • applications
  • network
  • databases
  • webServers
  • appServers
  • operatingSystems
  • miscellaneous
• Message Catalog: If provided, it must be the same as the agent name. The actual properties file containing localization data must be placed in the <IxoramRMS_installation_folder>/config/messages folder and the name must obey the following rule: The dots in the agent name are replaced by the underscore character and the properties extension is appended to lookup the file name.

Example: If the agent name is agents.myagent then the name of the properties file containing localization data must be agents_myagent.properties

The following agent definition data can be assigned to one or more agent versions by selecting the right entry in the "Data for version(s)" list and clicking on the "Edit" button:

• System Versions: Whether agent can monitor multiple versions of the same system. Providers can be associated to one or more versions defined here.
• Location: Whether the agent will be executed locally or deployed remotely.
• Levels: Whether agent supports multiple monitoring levels, and which is the default.
• Jar Paths: List of external jar files that agent may require.
• UI Jar: jar containing agent's user interface (configuration panel).
• Config Panel: Java class containing implementation of the configuration panel displayed in 'Activate Agent' window. If one of the agent templates has been chosen before this field will already be populated.

This version specific data is defined using the "Versionable Agent Intallation Data" dialog shown below.

Since version 1.1 of IxoraRMS, default values can be assigned for the configuration parameters of the agent. However this is not achievable yet through the user interface. The agent definition file needs to be modified if this is needed. This file is located at <IxoraRMS_installation_folder>/agents/<agent_id>/agent.

The following is an example of a custom JMX JSR 160 agent which has default values specified for some configuration parameters (the highlighted section):

Once the new agent is defined, providers of monitoring data can be assigned to it.

Providers

Access this window from "Tools" - "Provider Manager". To create a Provider, first select an Agent and click Add. This will bring up the Provider Instance Editor.

Common fields

• Agent Versions: available if the associated agent has defined a list of versions. Select which versions this provider is intended to work with.
• Provider Instance Name: Name for this provider
• Provider Instance Description: Description for this provider
• Type: Select either SQL, Java or Process from the dropdown list. Different provider types will have different configuration options, detailed below.
• Location: Run this provider localy (on the machine whereIxoraRMS console is running), remotely (on the monitored host) or wherever the agent is configured to run (inherit location).
• Optional: Provider can be enabled/disabled before agent is activated.
• Selected: The default enabled/disabled state of the provider.
• Requires private collector: Check this if the provider may occasionaly take much longer to execute. If this is selected the provider will not affect the functioning of the common data collectors. Be selective when enabling this flag as too many collectors will impact overall system performance.

Note that in all options detailed below you can use properties of the agent, through the following syntax: {agent.propertyname}. Thus, if the agent's configuration has a property called 'propertyname', its value will be used here. This makes it convenient for example to attach multiple SQL based providers, which will all use the username and password configured in the agent.

Along with the {agent.propertyname} syntax, the following built-in tokens can be used:

• {agent} : converts at runtime to agent's name.
• {host} : converts to name of the host that this agent is deployed on.
• {home} : converts to the folder where IxoraRMS is installed.
• {tick} : converts to the sampling interval configured for the agents in seconds.
• {tick.ms} : converts to the same sampling interval, but given in milliseconds.

Java specific options

• Classpath: Java classpath required by implementation class.
• Class loader id: The id of the class loader to use; Use the same id for multiple provider instances using the same code to allow sharing of resources.
• Implementation class: The name of the java class with the implementation for this provider.
• Implementation class parameters: Parameters list to be passed to the impplementation class. Each parameter must be between double quotes (e.g. "param1" "param2").

For more information on Java providers see "Java Providers".

Process specific options

• Command: Command line to execute.
• Process is volatile: Check this if the process returns a block of information and then exits. IxoraRMS will execute the command line each time it needs to retrieve data. Leave this unchecked if the process is continuously returning data.
• End of buffer regex: Regular expression that marks a line as being the end of a data buffer. If a process is not volatile and this parameter is left empty every line of output will be sent to the data parser otherwise lines will be buffered until a line where this regular expression has a match is found.
• Process remote execution mode: Set to one of the following values:
  • {agent.executionMode}: The provider will inherit the execution mode from the agent configuration.
  • Normal: The provider will be executed locally on the Console host.
  • Telnet: The provider will be executed using a Telnet session on the monitored host.
  • SSH2: The provider will be executed using a secure shell session on the monitored host.
• Username: Only applies for 'Telnet' or 'SSH2' execution modes: it is the username used to connect to the monitored host. The default value is {agent.Username} which allows the provider the use the value defined at agent level.
• Password: applies for 'Telnet' or 'SSH2' execution modes: it is the password used to connect to the monitored host. The default value is {agent.Password} which allows the provider the use the value defined at agent level.
• Shell prompt: applies for the 'Telnet' execution mode: it is the shell prompt for the telnet session. To find out this value log in first through a telnet terminal and using the username that you intend to use for the 'Username' parameter: The default value is {agent.ShellPrompt} which allows the provider the use the value defined at agent level
• Connection port: applies for 'Telnet' or 'SSH2' execution modes: it is the port used for the remote connection. The default value is {agent.Port} which allows the provider the use the value defined at agent level

SQL specific options

• Classpath: Classpath pointing to the JDBC driver code.
• Class loader id: The id of the class loader to use; Use the same id for multiple provider instances using the same code to allow sharing of resources.
• JDBC driver class: The name of the JDBC driver class.
• Username: Authenticate using this username.
• Password: Authenticate using this password.
• JDBC connection string: Connection string used to establish the database connection.
• SQL query: The SQL query to execute for data collection.

For more information on SQL providers see "SQL Providers".

Table parser options

• Convert column to row: If set to true converts the single column result of a query into a single row table; used to facilitate the use of a table parser instead of a properties parser(see the example below); by doing this one can group the data into a hierarchy of entities which would not be possible using the properties parser on this type of data
• Column separator: character(s) separating columns. Default is whitespace.
• Ignore lines matching: Each line of text will be search for this regular expression. A line containing it will be ignored by parser.
• Ignore data columns at: Use this to handle the situation where missing values for a cell can be the same as the column separator. This will allow you to ignore extra cells in rows of data.
• Accumulate volatile entities: if selected, entities generated dynamically (for example the list of processes on a system) will persist in the entity tree. If not selected dynamic entities will appear and dissapear as they are found or not in the data source.

Convert column to row example: If input data is:

10

22

4

5

506

269

then by using the conversion the output will be:

10 22 4 5 506 269

which can be now extracted into a hierarchy like this:

            root

   +- Networking 

           |    [Aborted_clients]

           |    [Aborted_connects]

    +- Traffic 

           |    [Bytes_received]

| [Bytes_sent]

   +- Binlog 

                [Binlog_cache_disk_use]

                [Binlog_cache_use]

Properties parser options

• Entity regex: A regular expression used to extract entity names. The regex must contain one capturing group. All matches of this group will generate an entity, which gets added under the Base entity (see the note below).
• Property/Value regex: A regular expression to extract name/value pairs. The regex must contain two capturing groups. By default matches for the first group will generate values, and matches for the second group will generate counter names.
• Value is second group: For the regex above, specifies whether the second group will generate values and the first will generate counter names.
• Base entity: All entities generated dynamically will be added under this base entity.
• Ignore lines matching: Each line of text will be search for this regular expression. A line containing it will be ignored by parser.
• Accumulate volatile entities: if selected, entities generated dynamically (for example the list of processes on a system) will persist in the entity tree. If not selected dynamic entities will appear and dissapear as they are found or not in the data source.

NOTE: Each counter resulted from parsing will need to have an entry in the list of counters, with a counter ID and an entity ID matching the ones extracted from text. If the regular expressions match values which are not in this list they will be ignored, without creating new counters or entities.

Example of a property parser definition:

For the command:

#netstat -s

Ip:

    1916 total packets received

    0 forwarded

    0 incoming packets discarded

    1696 incoming packets delivered

    1718 requests sent out

Icmp:

    0 ICMP messages received

    0 input ICMP message failed.

    ICMP input histogram:

    0 ICMP messages sent

    0 ICMP messages failed

    ICMP output histogram:

The parser definition is:

• Entity regex: ([^:].*):
• Property/Value regex: \s*([^\s]+)\s*([^\(]+).*
• Base entity: root/Network protocols

And the generated entities are:

Network protocols

   +- Ip

   |    [total packets received]

   |    [forwarded]

   |    [incoming packets discarded]

   |    [incoming packets delivered]

   |    [requests sent out]

   +- Icmp

        [ICMP messages received]

        [input ICMP message failed]

        [ICMP messages sent]

        [ICMP messages failed]

Column definition

Column definition is the main part of creating a provider. Each of the three provider types (SQL, Java and Process) will output a table. On this Parser page you are giving a meaning to each column of this table, by associating it with an Entity or Counter.

The parser needs to have definitions for all columns, regardless of whether they will be visible in the entity tree or not. To skip a column, leave the EntityID and CounterID empty for that particular column index.

To convert a column into a Counter, enter a CounterID and an EntityID for it. The CounterID is a simple text, which will be looked up in the agent's Message Catalog (see "Agent Installer"). If no translation is available for that text, the CounterID will be displayed as-is throughout IxoraRMS.

The syntax of an EntityID is:

root/e1/e2/...

where e1, e2 and so on are simple strings, localised in the same way as the CounterID. Each of these elements will result in an Entity being added to the tree. The final Entity in the path will contain the Counter.

To convert a column into an Entity, only enter an EntityID, but no CounterID.

To create dynamic (volatile) entities based on values in a certain column, use the syntax:

root/e1/{n}

where n is the index of the column containing entity names. The value between { and } can contain any characters, the rule is that any digit is treated as the index of a column. In the example below the PID of a process (found at column 0) is appended to the name (found at column 1) to build just one entity name.

root/Processes/{0#1} or root/Processes/{0-1}

An example of creating entities and counters out of the output of the Unix command ps:

# ps

   PID  CLS PRI TTY      TIME COMD

  5996   TS  70 pts004   0:00 sh

 18294   TS  59 pts004   0:00 ps

Parser definitions would be:

Column     EntityID              CounterID

0       root/Processes/{0}

1       root/Processes/{0}       Scheduling class

2       root/Processes/{0}       Priority

3       root/Processes/{0}       TTY

4       root/Processes/{0}       Time

5       root/Processes/{0}       Command line

And when the agent containing this provider is activated, the entity tree would look like:

Agent

  +- Processes

      +- 5996

      |   [Scheduling class]

      |   [Priority]

      |   [TTY]

      |   [Time]

      |   [Command line]

      +- 18294

          [Scheduling class]

          [Priority]

          [TTY]

          [Time]

          [Command line]

You can find more complex examples in the definitions of some IxoraRMS's own agents, such as Linux or Oracle.

The Descriptors tab allows entering descriptions and types for entities and counters:

• Description (for both entities and counters): simple string which can be translated, or displayed as is.
• Type: choose double, long or string for this counter, which will affect how it is displayed in charts.
• Discrete: check if this counter does not have continuous values (for example it's an error code), may affect the way it is displayed in some charts.