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:
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:
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.
Common fields:
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:
Java specific options:
Process specific options:
SQL specific options:
Table parser options:
Properties parser options:
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: