Configuration

There three configuration files, located in $JLUPIN_HOME/jmx-extractor/configuration directory:

  • jmx-extractor.log4j2.xml - the standard configuration file for Log4j2, it won't be discussed further.
  • setenv - initial configuration
  • jmx-extractor.yml - runtime configuration

setenv - initial configuration

Initial configuration, used by runtime scripts during JMX Extractor startup, it contains the following parameters:

  • JAVA_HOME - Set JAVA_HOME manually if you want to use specific JAVA binaries or JAVA discovery fails.
  • JAVA_OPTS - Java options, the defaults are fine for most use cases,
  • CONFIGURATION_FILE - if you want to place the runtime configuration file (jmx-extractor.yml) in the custom location, you can set it here.

jmx-extractor.yml - runtime configuration

Runtime configuration, used by runtime JMX Extractor to perform data collection from MBeans via JMX interface, it consists of the following sections:

  • logging - logging configuration
  • connection - JMX connection proprieties
  • printer - the set of parameters that defines how output data is formatted
  • attributes - output formatting

Section 'logging'

The appropriate part of configuration file:

logging:
  configuration: configuration/jmx-extractor.log4j2.xml
[...]

Description:

Parameter Description
configuration the path to log4j2 configuration file

Section 'connection'

The appropriate part of configuration file:

[...]
connection:
  address: 127.0.0.1
  jmxPort: 9010
[...]

Description:

Parameter Description
address IP address of JLupin node.
jmxPort JMX port of Main Server (!) running on the node.

Section 'printer'

The appropriate part of configuration file:

[...]
printer:
  type: standard
  separator: ';'
[...]

Description:

Parameter Description
type The format of the output. In addition to the tree format ('standard') you can use: 'separated' (like csv), 'json', 'xml'.
separator Separator between a key (combined MBean name and its attribute) and it value (applicable when 'separated' type is chosen).

Section 'attributes'

This section contains the list of MBeans and their attributes that are requested for data collection. It consists of two subsections:

  • mainServer - the list for JLupin Main Server
  • microservices - the list for microservices

In microservices section the common subsection is defined which applied to all microservices. You can define additional subsections for individual microservices to collect specific data. In that case the name of the subsection should be the same as microservice's name.

General structure of attribute section is as follows:

[...]
attributes:
  mainServer:
    [...]            <-- MBeans & attributes definitions for Main Server
  microservices:
    common:
      [...]            <-- MBeans & attributes definitions for all microservices
    microservice1:
      [...]            <-- MBeans & attributes definitions for microservice1
    microservice2:
      [...]            <-- MBeans & attributes definitions for microservice2

MBeans and their attributes are also hierarchically structured, ended with boolean value (true | false) which controls if specific attribute should be monitored (if attribute / MBean is not present in the configuration it will be omitted by default):

[...]
attributes:
  mainServer:
    '<MBean1_name>':
      'MBean1_attribute1_name': true    <-- this will be monitored
      'MBean1_attribute2_name': true    <-- this will be monitored
      'MBean1_attribute3_name': false   <-- this will be omitted
  microservices:
    common:
      '<MBean1_name>':
        'MBean1_attribute1_name': true    <-- this will be monitored
        'MBean1_attribute2_name': false   <-- this will be omitted

Some attributes are defined as a complex data type, usually as 'key->value' lists. Most of them are supported by JMX extractor, each 'value' hidden under 'key' can be pointed out in the configuration:

[...]
attributes:
  mainServer:
    '<MBean1_name>':
      'MBean1_attribute1_name': <-- complex data type
        'key1': true            <-- value for key1
        'key2': true            <-- value for key2
      'MBean1_attribute2_name': true    
  microservices:
    common:
      '<MBean1_name>':
        'MBean1_attribute1_name': true

A good example is heap usage, which is defined as follows:

[...]
attributes:
  mainServer:
    'java.lang:type=Memory':
        'HeapMemoryUsage':
            'init': true
            'max': true
            'used': true
            'committed': true
[...]

NOTE If you want to defined and register your own custom MBean we advice to use java Map type object, which can be easily configured in JMX Extractor (we used it for our com.jlupin.jmx:type=allEnvironmentState MBean)

You can also defined MBeans / attributes / keys through regular expressions. In that case the name should begin with r/ and ended with / with regular expression inside it, as in the following pattern:

[...]
attributes:
  mainServer:
    'r/<regular_expr_1>/':                <-- regular expression for MBean name
      'MBean1_attribute1_name':           
        'r/<regular_expr_2>/': true       <-- regular expression for keys
      'MBean1_attribute2_name': true    
  microservices:
    common:
      '<MBean1_name>':
        'MBean1_attribute1_name': true
[...]

For example, to read given set of attributes of all discovered Garbage Collectors you can define:

[...]
attributes:
  mainServer:

'r/^java.lang:type=GarbageCollector,name=.*/':
    'CollectionCount': true
    'CollectionTime': true
[...]

Default configuration

In default configuration we provide basic parameters, suitable for most use cases. Enjoy :)

logging:
  configuration: configuration/jmx-extractor.log4j2.xml
connection:
  address: 127.0.0.1
  jmxPort: 9010
printer:
  type: standard
  separator: ';'
attributes:
  mainServer:
    'com.jlupin.jmx:type=allEnvironmentState':
        'AllEnvironmentState':
            'MAIN_SERVER':
                'RUNTIME':
                    'cpu':
                        'jvmProcessCpuUtil': true
                    'eventLog': true
                    'memory':
                        'jvmFreeMemory': true
                        'jvmMaxMemory': true
                        'jvmTotalMemory': true
                    'servers':
                        'ELASTIC_HTTP':
                            'activeThreads': true
                            'maxThreads': true
                        'INFORMATION':
                            'activeThreads': true
                            'maxThreads': true
                        'INFORMATION_HTTP':
                            'activeThreads': true
                            'maxThreads': true
                        'JLRMC':
                            'activeThreads': true
                            'maxThreads': true
                        'QUEUE':
                            'activeThreads': true
                            'maxThreads': true
                        'TRANSMISSION':
                            'activeThreads': true
                            'maxThreads': true
                    'state':
                        'isActivated': true
                        'isMainServerDeactivatedForce': false
            'MICROSERVICES':
                'RUNTIME':
                    'cpu':
                        'r/.*/':
                            'jvmProcessCpuUtil': true
                    'r/.*/':
                        'currency-converter-chf':
                            'jvmFreeMemory': true
                            'jvmMaxMemory': true
                            'jvmTotalMemory': true
                    'pid':
                        'r/.*/': true
                    'servers':
                        'r/.*/':
                            'HTTP':
                                'activeSessions': true
                                'servletActiveThreads': true
                                'servletMaxThreads': true
                            'JLRMC':
                                'jrmcActiveThreads': true
                                'jrmcMaxThreads': true
                            'QUEUE':
                                'queueActiveThreads': true
                                'queueMaxThreads': true
                    'state':
                        'r/.*/':
                            'available': true
                            'isActivated': true
                            'userAvailableFlag': true
            'OS':
                'RUNTIME':
                    'cpu':
                        'cpuUtil': true
                    'memory':
                        'free': true
                        'total': true
            'TECH_MICROSERVICES':
                'RUNTIME':
                    'nginx':
                        'processId': true
                        'running': true
    'r/^java.lang:type=GarbageCollector,name=.*/':
        'CollectionCount': true
        'CollectionTime': true
    'java.lang:type=Memory':
        'HeapMemoryUsage':
            'init': true
            'max': true
            'used': true
            'committed': true
        'NonHeapMemoryUsage':
            'init': true
            'max': true
            'used': true
            'committed': true
    'r/^java.lang:type=MemoryPool,name=.*/':
        'Usage':
            'init': true
            'max': true
            'used': true
            'committed': true
    'java.lang:type=Threading':
        'ThreadCount': true
        'PeakThreadCount': true
        'DaemonThreadCount': true
    'r/^java.nio:type=BufferPool,name=.*/':
        'TotalCapacity': true
        'MemoryUsed': true
    'java.lang:type=OperatingSystem':
        'MaxFileDescriptorCount': true
        'OpenFileDescriptorCount': true
  microservices:
    common:
        'r/^java.lang:type=GarbageCollector,name=.*/':
            'CollectionCount': true
            'CollectionTime': true
        'java.lang:type=Memory':
            'HeapMemoryUsage':
                'init': true
                'max': true
                'used': true
                'committed': true
            'NonHeapMemoryUsage':
                'init': true
                'max': true
                'used': true
                'committed': true
        'r/^java.lang:type=MemoryPool,name=.*/':
            'Usage':
                'init': true
                'max': true
                'used': true
                'committed': true
        'java.lang:type=Threading':
            'ThreadCount': true
            'PeakThreadCount': true
            'DaemonThreadCount': true
        'r/^java.nio:type=BufferPool,name=.*/':
            'TotalCapacity': true
            'MemoryUsed': true
        'java.lang:type=OperatingSystem':
            'MaxFileDescriptorCount': true
            'OpenFileDescriptorCount': true