wbrefvem/python-jolokia

Python client for Jolokia, an HTTP-JMX bridge

python-jolokia

This is a python client library for Jolokia.

Motivation

Jolokia provides a JMX to HTTP bridge, which opens up many possibilities for managing JMX-enabled applications outside conventional enterprise Java workflows. At present, backend libraries are only available for Java and Perl, and there's also a browser-side JavaScript library. While Python is generally more convenient for dealing with HTTP resources than Java or Perl, a client library for Jolokia is optimal.

JMX is not a platform-agnostic tech. This means that management applications for Java EE apps are almost always written in Java, which is unfortunate, as it prevents a more flexible, polyglot architecture. Enter Jolokia. By bridging JMX to HTTP, Jolokia brings Java application management into the broader world of the web, so that they can be orchestrated and managed by tools outside the stodgy, if stable, world of enterprise Java.

Goals

Create a Python client for Jolokia that makes JMX data available both through simple abstractions aimed at the non-Java developer as well as through a full-featured API that gives the seasoned Java developer the flexibility she craves.

Requirements

• Support all Python versions supported by Python maintainers (currently >=3.5)
• python-jolokia should be transparent to different versions of the Jolokia protocol.

Installation

For regular usage, the recommended (but not required) installation method is pipenv:

pipenv install jolokia

For hacking on python-jolokia, pipenv is required. Fork the repo, clone it, and install dev dependencies:

git clone https://github.com/<user|org>/python-jolokia.git
pipenv install --dev

Usage

For HTTP authentication you can pass a in username and password

from jolokia import JolokiaClient


jc = JolokiaClient('http://my-jolokia-enabled-server.com/jolokia', 'my_login', 'my_password')

To get a single attribute of an MBean:

from jolokia import JolokiaClient


jc = JolokiaClient('http://my-jolokia-enabled-server.com/jolokia')

resp = jc.get_attribute(mbean='java.lang:type=Memory', attribute='HeapMemoryUsage')

print(resp)

{
    'request': {
        'attribute': 'HeapMemoryUsage', 
        'mbean': 'java.lang:type=Memory', 
        'type': 'read'
    }, 
    'timestamp': 1496174821, 
    'value': {
        'used': 288902152, 
        'committed': 1310720000, 
        'max': 1310720000, 
        'init': 1367343104
    }, 
    'status': 200
}

Or to retrieve multiple attributes, pass a list as the attribute parameter:

resp = jc.get_attribute(
    mbean='java.lang:type=Memory', 
    attribute=['HeapMemoryUsage', 'NonHeapMemoryUsage']
)

print(resp)

{
    'request': {
        'type': 'read', 
        'attribute': ['HeapMemoryUsage', 'NonHeapMemoryUsage'], 
        'mbean': 'java.lang:type=Memory'
    }, 
    'value': {
        'NonHeapMemoryUsage': {
            'init': 2555904, 
            'max': 1593835520, 
            'used': 77620176, 
            'committed': 87556096
        }, 
        'HeapMemoryUsage': {
            'init': 1367343104, 
            'max': 1310720000, 
            'used': 367638816, 
            'committed': 1310720000
        }
    }, 
    'timestamp': 1496175578, 
    'status': 200
}

Setting attributes works the same way, except that the value parameter is also required:

resp = jc.set_attribute(
    mbean='java.lang:type=ClassLoading',
    attribute='Verbose',
    value=True
)

print(resp)

{
    'request': {
        'type': 'write', 
        'attribute': 'Verbose', 
        'mbean': 'java.lang:type=ClassLoading', 
        'value': True
    }, 
    'value': False, 
    'timestamp': 1496175995, 
    'status': 200
}

Note that the top-level value key in the response refers to the initial value, and we can run get_attribute to verify that the value is now set to our specified value:

resp = jc.get_attribute(mbean='java.lang:type=ClassLoading', attribute='Verbose')

print(resp)

{
    'request': {
        'type': 'read', 
        'attribute': 'Verbose', 
        'mbean': 'java.lang:type=ClassLoading'
    }, 
    'value': True, 
    'timestamp': 1496176091, 
    'status': 200
}

Contributing

Coming soon...

python-jolokia's Issues

Multiple attributes in get_attribute returns only the first one

When passing in a list of attributes into get_attribute only the first attribute is returned. Looking in the source I see that a list of individual json payloads are generated and then sent.

I dont know if things have changed for jolokia since the birth of this project but this doesn't work as the return is only the first attribute supplied in the list. According to jolokia docs a json array of attributes is to be passed in, not a list of separate individual payloads of each attribute. I'm not sure if this is an in general thing or just because I'm dealing with AMQ and its a bit different.

In any case if you pass a comma separated string of your list as the attribute that also works and returns the bulk listing of all your attributes.

Flesh out and publish docs

Documentation should be completed, built with sphinx, and hosted somewhere.

Rewrite set_attribute to explicitly accept list of attribute-value pairs

Currently, the set_attribute method can perform a bulk write if passed a list of attributes and :

def set_attribute(self, mbean=None, attribute=None, value=None, path=None, *args, **kwargs):
        """Sets the value of an MBean's attribute"""

        if not mbean or not attribute or not value:
            raise IllegalArgumentException('set_attribute method has 3 required parameters: mbean, attribute, and value')

        if type(attribute) is list and type(value) is dict:
            return self._bulk_write(mbean, attribute, value, **kwargs)
        elif (type(attribute) is list and type(value) is not dict) or (type(attribute) is not list and type(value) is dict):
            raise IllegalArgumentException('Bulk writes must include an attribute list and an attribute map')

This clunky and unintuitive. set_attribute should take an optional boolean called bulk and a list of attribute-value tuples as a co-requirement if bulk = True.

DRY out tests

Currently, mock methods used to monkey patch requests.Session are repetitive¹ and should be refactored according to the DRY principle.²

Cleanup CI build, setup Jenkins to do Codeship preliminaries

Authentication to Jolokia endpoint

Hi,
I looked both in documentation and source but can't seem to find how to do an authenticated call to the Jolokia endpoint. Is it a missing feature or does it have an implicit syntax?
Thanks,

Marco