Skip to content

JMX Integration

Infrastructure Integration

Instructions

Follow the installation guide below for your given collector environment.

During installation, use the configuration section below as reference.

After installation, the infrastructure datasources in the table below will be available in the AOC.

Installation Guide

Installing this integration consists of creating a yaml file in the filesystem of your collectors. Click below for instructions on how to do so for your given collectors environment.

Docker

Kubernetes

Mesos-Marathon

Debian

Ubuntu

RHEL/CentOS

Configuration

  1. Ensure that you can open a JMX remote connection.
  2. Edit jmx.yaml to configure the agent.
      init_config:
        custom_jar_paths: # optional
          - /path/to/custom/jarfile.jar
        #is_jmx: true
    
      instances:
        - host: localhost
          port: 7199
          user: username
          password: password
    
          jmx_url: "service:jmx:rmi:///jndi/rmi://myhost.host:9999/custompath" # optional
    
          name: jmx_instance  # optional
          java_bin_path: /path/to/java
          java_options: "-Xmx200m -Xms50m"
          trust_store_path: /path/to/trustStore.jks
          trust_store_password: password
    
          process_name_regex: .*process_name.*
          tools_jar_path: /usr/lib/jvm/java-7-openjdk-amd64/lib/tools.jar
          refresh_beans: 600 # optional (in seconds)
          tags:
            env: stage
            newTag: test
    
          conf:
            - include:
                domain: my_domain
                tags:
                    simple: $attr0
                    raw_value: my_chosen_value
                    multiple: $attr0-$attr1
                bean:
                  - my_bean
                  - my_second_bean
                attribute:
                  attribute1:
                    metric_type: counter
                    alias: jmx.my_metric_name
                  attribute2:
                    metric_type: gauge
                    alias: jmx.my2ndattribute
            - include:
                domain: 2nd_domain
              exclude:
                bean:
                  - excluded_bean
            - include:
                domain_regex: regex_on_domain
              exclude:
                bean_regex:
                  - regex_on_excluded_bean
    

Configuration Options

  • custom_jar_paths (Optional) - Allows specifying custom jars that will be added to the classpath of the agent’s JVM.
  • jmx_url - (Optional) - If the agent needs to connect to a non-default JMX URL, specify it here instead of a host and a port. If you use this you need to specify a ‘name’ for the instance.
  • is_jmx (Optional) - Allows creating different configuration files for each application rather than using a single long jmx file. Include the option in each configuration file.
  • name - (Optional) - Used in conjunction with jmx_url.
  • java_bin_path - (Optional) - Should be set if the agent cannot find your java executable.
  • java_options - (Optional) - Java JVM options
  • trust_store_path and trust_store_password - (Optional) - Should be set if ssl is enabled.
  • process_name_regex - (Optional) - Instead of specifying a host and port or jmx_url, the agent can connect using the attach api. This requires the JDK to be installed and the path to tools.jar to be set.
  • tools_jar_path - (Optional) - To be set when process_name_regex is set.
  • refresh_beans - (Optional) - Refresh period for refreshing the matching MBeans list. Default is 600 seconds. Decreasing this value may result in increased CPU usage.

The conf parameter is a list of dictionaries. Only 2 keys are allowed in this dictionary:

  • include (mandatory): Dictionary of filters, any attribute that matches these filters will be collected unless it also matches the exclude filters (see below)
  • exclude (optional): Another dictionary of filters. Attributes that match these filters won’t be collected

Tags are automatically added to metrics based on the actual MBean name. You can explicitly specify supplementary tags. For instance, assuming the following MBean is exposed by your monitored application:

mydomain:attr0=val0,attr1=val1

It would create a metric called mydomain (or some variation depending on the attribute inside the bean) with tags:

attr0:val0, attr1:val1, domain:mydomain, simple:val0, raw_value:my_chosen_value, multiple:val0-val1

If you specify an alias in an include key that is formatted as camel case, it will be converted to snake case. For example, MyMetricName will be shown in Epoch as my_metric_name.

Description of the filters

Each include or exclude dictionary supports the following keys:

  • domain: a list of domain names (e.g. java.lang)
  • domain_regex: a list of regexes on the domain name (e.g. java.lang.*)
  • bean or bean_name: A list of full bean names (e.g. java.lang:type=Compilation)
  • bean_regex: A list of regexes on the full bean names (e.g. java.lang.[,:]type=Compilation.)
  • attribute: A list or a dictionary of attribute names (see below for more details)

The regexes defined in domain_regex and bean_regex must conform to Java’s regular expression format.

On top of these parameters, the filters support “custom” keys which means that you can filter by bean parameters. For example, if you want to collect metrics regarding the Cassandra cache, you could use the type: - Caches filter:

    conf:
    - include:
        domain: org.apache.cassandra.db
        type:
          - Caches

The attribute filter

The attribute filter can accept two types of values: 1. A dictionary whose keys are attributes names:

      conf:
      - include:
            attribute:
              maxThreads:
                alias: tomcat.threads.max
                metric_type: gauge
              currentThreadCount:
                alias: tomcat.threads.count
                metric_type: gauge
              bytesReceived:
                alias: tomcat.bytes_rcvd
                metric_type: counter

In that case you can specify an alias for the metric that will become the metric name in Epoch. You can also specify the metric type either a gauge or a counter. If you choose counter, a rate per second will be computed for this metric.

  1. A list of attributes names: yaml conf: include: domain: org.apache.cassandra.db attribute: BloomFilterDiskSpaceUsed BloomFilterFalsePositives BloomFilterFalseRatio Capacity CompressionRatio CompletedTasks ExceptionCount Hits RecentHitRate

In that case: The metric type will be a gauge The metric name will be jmx.[DOMAIN_NAME].[ATTRIBUTE_NAME]

Here is another filtering example:

instances:
  - host: 127.0.0.1
    name: jmx_instance
    port: 9999

init_config:
  conf:
    - include:
        bean: org.apache.cassandra.metrics:type=ClientRequest,scope=Write,name=Latency
        attribute:
          - OneMinuteRate
          - 75thPercentile
          - 95thPercentile
          - 99thPercentile

Infrastructure Datasources

The below metrics are gauged every 10 seconds.

Datasource Unit Description
jvm.heap_memory byte The total Java heap memory used.
jvm.heap_memory_committed byte The total Java heap memory committed to be used.
jvm.heap_memory_init byte The initial Java heap memory allocated.
jvm.heap_memory_max byte The maximum Java heap memory available.
jvm.non_heap_memory byte The total Java non-heap memory used.
jvm.non_heap_memory_committed byte The total Java non-heap memory committed to be used.
jvm.non_heap_memory_init byte The initial Java non-heap memory allocated.
jvm.non_heap_memory_max byte The maximum Java non-heap memory available.
jvm.thread_count thread The number of live threads.
jvm.gc.cms.count count The total number of garbage collections that have occurred.
jvm.gc.parnew.time millisecond The approximate accumulated garbage collection time elapsed.