The `jmx` metricset collects metrics from
https://jolokia.org/reference/html/agents.html[Jolokia agents].

[float]
=== Features and configuration
Tested with Jolokia 1.5.0.

To collect metrics from a Jolokia instance, define a mapping section that
specifies an MBean `ObjectName` followed by an array of attributes to fetch. For
each attribute in the array, specify the Elastic field name where the
returned value will be saved. 

For example, to get the `Uptime` attribute from the `java.lang:type=Runtime`
MBean and map it to an event field called `jolokia.testnamespace.uptime`,
configure the following mapping:

[source,yaml]
----
- module: jolokia
  metricsets: ["jmx"]
  hosts: ["localhost:8778"]
  namespace: "testnamespace" <1>
  jmx.mappings:
    - mbean: 'java.lang:type=Runtime'
      attributes:
        - attr: Uptime
          field: uptime <2>
          event: uptime <3>
      target:
          url: "service:jmx:rmi:///jndi/rmi://targethost:9999/jmxrmi"
          user: "jolokia"
          password: "s!cr!t"
----
<1> The `namespace` setting is required. This setting is used along with the
module name to qualify field names in the output event.
<2> The field where the returned value will be saved. This field will be called
`jolokia.testnamespace.uptime` in the output event.  
<3> The `event` setting is optional. Use this setting to group all attributes
with the same `event` value into the same event when sending data to Elastic. 

If the underlying attribute is an object (such as the `HeapMemoryUsage`
attribute in `java.lang:type=Memory`), its structure will be published to
Elastic "as is".

You can configure nested metric aliases by using dots in the mapping name (for
example, `gc.cms_collection_time`). For more examples, see
https://github.com/elastic/beats/blob/{doc-branch}/metricbeat/module/jolokia/jmx/_meta/test/config.yml[/jolokia/jmx/test/config.yml].

All metrics from a single mapping will be POSTed to the defined host/port and
sent to Elastic as a single event. To make it possible to differentiate between
metrics from multiple similar applications running on the same host, you should
configure multiple modules.

When wildcards are used, an event is sent to Elastic for each matching
MBean, and an `mbean` field is added to the event.

[float]
=== Limitations
All Jolokia requests have `canonicalNaming` set to `false`. See the
https://jolokia.org/reference/html/protocol.html[Jolokia Protocol] documentation
for more detail about this parameter.


[float]
=== Exposed fields, dashboards, indexes, etc.
Because this module is very general and can be tailored for any application that
exposes its metrics over Jolokia, it comes with no exposed field descriptions,
dashboards, or index patterns.