# OSGI Info Plugin

The Info OSGI Plugin was developed as a mean of monitoring the qpid broker startup/shutdown times along with selected JVM and OS details. It was written as a OSGI plugin so it can be used as needed.

## How it works

Assuming the plugin is deployed, upon the Activator invocation (which happens when OSGI loads the bundles), the plugin looks for its configuration file. If the file cannot be found, the plugin does not perform any operation and will silently exit. If the configuration is found, it is loaded and parsed. A predefined set of data is collected and messages are generated as per the configuration templates (see below for details).

Further, the messages are sent using one of the supported protocols (currently http post and soap) to the configured destination. The same scenario takes place on the plugin unload phase which usually takes place upon broker shutdown.

## Data Gathering

The info plugin collects a pre-defined set of data, and generates a message according to a template defined in each section of the ini file. Data can be of 2 categories:

1. JVM specific

2. application specific

Each data has a variable name associated which can be used for the message generation template. The convention chosen for template is: @[variable (in uppercase)] (eg @IP, @PORT) (see configuration section for message examples).

The following application specific info are gathered (variable names in round brackets):

1. The JMX Port the application is listening to (jmxport)

2. The Port(s) the broker is listening to, comma delimited (port)

3. The Broker Version (version)

4. The key store path (KeystorePath)

5. The Plugin Directory (PluginDirectory)

6. The QPID work directory (QpidWork)

7. The JMX Principal Database (JMXPrincipalDatabase)

The following JVM specific info are collected (variable names in round brackets):

1. Hostname (hostname)

2. IP address of the current machine (ip)

3. Number of CPU cores (CPUCores)

4. Maximum memory (Maximum_Memory)

5. Free Memory (Free_Memory)

6. Java Class Path (java.class.path)

7. Jave Home (java.home)

8. Java VM Name (java.vm.name)

9. Java VM Vendor (java.vm.vendor)

10. Java VM Version (java.vm.version)

11. Java Class Version (java.class.version)

12. Java Runtime Version (java.runtime.version)

13. OS Architecture (os.arch)

14. Sun Architecture Data Model (sun.arch.data.model)

15. User home directory (user.home)

16. User Name (user.name)

17. User Time Zone (user.timezone)

## Plugin Configuration

The plugin configuration file is currently hardcoded to be: $QPID_HOME/etc/qpidinfo.ini We plan to provide a mean to change the configuration by using system property (eg -DInfoPluginConfig) but currently this is not available.

As it might be useful to send more than 1 message, eventually to different destinations, we chose an ini file layout for the plugin configuration that consists of a global section and set of individual sections, one for each message to be sent.

The configuration file has a global section composed of any key-value pairs placed before the start of an ini-type section (eg [section]). The role of the global section is to provide a set of values that would be inferred in each subsequent section. Any section from the config file can override any global variable by specifying the respective key-value pair inside.

The key protocol is mandatory, the plugin will not work if protocol=soap or protocol=http is not specified. For soap, we expect the following keys to be present:

- soap.hostname

- soap.port

- soap.path

- soap.envelope

For http the following keys have to be present:

- http.url

- http.envelope

The names are self-explanatory, please see the example below. The protocol key cannot be overwritten in the sections and it has to be chosen initially.

## Example Configuration

For soap messages, we will abbreviate the XML header by omitting the namespaces in the config, in order to be more readable. A minimal correct XML for the soap envelope would be

       <?xml version=\"1.0\"?>
       <soap:Envelope
          xmlns:soap=\"http://www.w3.org/2001/12/soap-envelope\"
          soap:encodingStyle=\"http://www.w3.org/2001/12/soap-encoding\">
          ...some content...
       </soap:Envelope>

NB. On the ini file, there can be no text wrapping for any entry (as above), the whole text should come into a single line, irrespective of how long it is.

    ## Ini file using SOAP
    protocol=soap
    soap.hostname=host1
    soap.port=8080

    [Message1]
    soap.path=/axis2/services/QpidInfo
    soap.action=qpidevent
    soap.envelope=<?xml version=\"1.0\"?><soap:Envelope>@ACTION-@VERSION</soap:Envelope>

    [Message2]
    soap.hostname=host2
    soap.port=9090
    soap.path=/axis1/services/Info
    soap.envelope=<?xml version=\"1.0\"?><soap:Envelope">@ACTION-@VERSION from @IP:@PORT</soap:Envelope>

    ##  End of File

and another example, this time using http:

    protocol=http
    http.url=http://mywebserver:8080/postServlet

    [Message1]
    http.envelope=Event from qpid broker at: @IP, running qpid version: @VERSION

    [Message2]
    http.url=http://myotherwebserver:9090/postServlet1
    http.envelope=Event for qpid broker @VERSION from @IP:@PORT running java @JAVA.VM.VERSION

The ini file is supporting comments starting with # or ; anywhere in the file. The global section is considered to be the first set of lines from the ini file before the first [Section] encountered.