Monitoring Custom Data

Another exciting feature of LivePerf is the ability to add custom data sources 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 data source are:

Agent Installer

This window is accessible from Tools/Agent Installer. To add a new Agent, click Install and select a configuration template (SQL, Java or Process). This will populate the fields with appropriate values, and will be enough for most uses. Here is a reference of the agent's properties, some of them are intended for future advanced customizations:

  • 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.
  • Location: Whether the agent will be executed locally or deployed remotely.
  • Levels: Whether agent supports multiple monitoring levels, and which is the default.
  • System Versions: Whether agent can monitor multiple versions of the same system. Providers can be associated to one or more versions defined here.
  • Jar Paths: List of external jar files that agent may require.
  • UI Jar: jar containing agent's user interface (configuration panel) for situations when agent's main body runs in a separate JVM instance.
  • Config Panel: Java class containing implementation of the configuration panel displayed in Activate Agent window.
  • Message Catalog: Usually the same as agent name, the name of properties file (located under config/messages), if any, containing message translations.
Agent Installer

Figure 17. Agent Installer

Providers

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

Provider Instsance Editor

Figure 18. Provider Instsance 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 where LivePerf 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. Requests for data will not be queued, to avoid suffocating the provider.

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 LivePerf is installed.
  • {tick} : converts to the sampling interval configured for the agents.
  • {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").

Process specific options:

  • Command: Command line to execute.
  • End of buffer: The line marking the end of a multiline buffer, for processes returning continuous blocks of information.
  • Process is volatile: Check this if the process returns a block of information and then exits. LivePerf will execute the command line each time it needs to retrieve data. Leave this unchecked if the process is continuously returning data.

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.

Table parser options:

  • 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.
  • 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.

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 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 LivePerf.

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.

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 LivePerf'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.