[[jmx_mgmt_tooling]]
==  Management Tooling
Management of {brandname} instances is all about exposing as much relevant statistical information that allows administrators to get a view of the state of each {brandname} instance. Taking in account that a single installation could be made up of several tens or hundreds {brandname} instances, providing clear and concise information in an efficient manner is imperative. The following sections dive into the range of management tooling that {brandname} provides.

=== JMX
Over the years, link:http://www.oracle.com/technetwork/java/javase/tech/javamanagement-140525.html[JMX] has become the de facto standard for management and administration of middleware and as a result, the {brandname} team has decided to standardize on this technology for the exposure of management and statistical information.

==== Understanding The Exposed MBeans
By connecting to the VM(s) where {brandname} is running with a standard JMX GUI such as link:https://docs.oracle.com/javase/8/docs/technotes/guides/management/jconsole.html[JConsole] or link:https://docs.oracle.com/javase/8/docs/technotes/guides/visualvm/[VisualVM] you should find the following MBeans:

*  For CacheManager level JMX statistics, without further configuration, you should see an MBean called _org.infinispan:type=CacheManager,name="DefaultCacheManager"_ with link:{javadocroot}/jmxComponents.html#CacheManager[properties specified by the CacheManager MBean] .

*  Using the cacheManagerName attribute in globalJmxStatistics XML element, or using the corresponding GlobalJmxStatisticsConfigurationBuilder.cacheManagerName(String cacheManagerName) call, you can name the cache manager in such way that the name is used as part of the JMX object name. So, if the name had been "Hibernate2LC", the JMX name for the cache manager would have been: _org.infinispan:type=CacheManager,name="Hibernate2LC"_ . This offers a nice and clean way to manage environments where multiple cache managers are deployed, which follows link:http://www.oracle.com/technetwork/java/javase/tech/best-practices-jsp-136021.html[JMX best practices] .

*  For Cache level JMX statistics, you should see several different MBeans depending on which configuration options have been enabled. For example, if you have configured a write behind cache store, you should see an MBean exposing properties belonging to the cache store component. All Cache level MBeans follow the same format though which is the following: `org.infinispan:type=Cache,name="${name-of-cache}(${cache-mode})",manager="${name-of-cache-manager}",component=${component-name}` where:

*  ${name-of-cache} has been substituted by the actual cache name. If this cache represents the default cache, its name will be `___defaultCache`.

*  ${cache-mode} has been substituted by the cache mode of the cache. The cache mode is represented by the lower case version of the possible enumeration values shown link:{javadocroot}/org/infinispan/configuration/cache/CacheMode[here].

*  ${name-of-cache-manager} has been substituted by the name of the cache manager to which this cache belongs. The name is derived from the _cacheManagerName_ attribute value in `globalJmxStatistics` element.

*  ${component-name} has been substituted by one of the JMX component names in the link:{javadocroot}/jmxComponents.html[JMX reference documentation] .

For example, the cache store JMX component MBean for a default cache configured with synchronous distribution would have the following name: `org.infinispan:type=Cache,name="___defaultcache(dist_sync)",manager="DefaultCacheManager",component=CacheStore`

Please note that cache and cache manager names are quoted to protect against illegal characters being used in these user-defined names.

==== Enabling JMX Statistics
The MBeans mentioned in the previous section are always created and registered in the MBeanServer allowing you to manage
your caches but some of their attributes do not expose meaningful values unless you take the extra step of enabling
collection of statistics. Gathering and reporting statistics via JMX can be enabled at 2 different levels:

.CacheManager level
The CacheManager is the entity that governs all the cache instances that have been created from it.
Enabling CacheManager statistics collections differs depending on the configuration style:


* If configuring the CacheManager via XML, make sure you add the following XML under the `<cache-container />` element:

 <cache-container statistics="true"/>

* If configuring the CacheManager programmatically, simply add the following code:

 GlobalConfigurationBuilder globalConfigurationBuilder = ...
 globalConfigurationBuilder.globalJmxStatistics().enable();

.Cache level
At this level, you will receive management information generated by individual cache instances.
Enabling Cache statistics collections differs depending on the configuration style:

* If configuring the Cache via XML, make sure you add the following XML under the one of the top level cache elements, such as `<local-cache />`:

 <local-cache statistics="true"/>

* If configuring the Cache programmatically, simply add the following code:

 ConfigurationBuilder configurationBuilder = ...
 configurationBuilder.jmxStatistics().enable();

==== Monitoring cluster health

It is also possible to monitor {brandname} cluster health using JMX. On CacheManager there's an additional object called `CacheContainerHealth`. It contains the following attributes:

* cacheHealth - a list of caches and corresponding statuses (HEALTHY, UNHEALTHY or REBALANCING)
* clusterHealth - overall cluster health
* clusterName - cluster name
* freeMemoryKb - Free memory obtained from JVM runtime measured in KB
* numberOfCpus - The number of CPUs obtained from JVM runtime
* numberOfNodes - The number of nodes in the cluster
* totalMemoryKb - Total memory obtained from JVM runtime measured in KB

==== Multiple JMX Domains
There can be situations where several CacheManager instances are created in a single VM, or Cache names belonging to different CacheManagers under the same VM clash.

Using different JMX domains for multi cache manager environments should be last resort.
Instead, it's possible to name a cache manager in such way that it can easily be identified and used by monitoring tools. For example:


* Via XML:

[source,xml]
----
<cache-container statistics="true" name="Hibernate2LC"/>
----


* Programmatically:

[source,java]
----
GlobalConfigurationBuilder globalConfigurationBuilder = ...
globalConfigurationBuilder.globalJmxStatistics()
    .enable()
    .cacheManagerName("Hibernate2LC");

----

Using either of these options should result on the CacheManager MBean name being: `org.infinispan:type=CacheManager,name="Hibernate2LC"`

For the time being, you can still set your own jmxDomain if you need to and we also allow duplicate domains, or rather duplicate JMX names, but these should be limited to very special cases where different cache managers within the same JVM are named equally.

==== Registering MBeans In Non-Default MBean Servers
Let's discuss where {brandname} registers all these MBeans. By default, {brandname} registers them in the link:{jdkdocroot}/java/lang/management/ManagementFactory.html#getPlatformMBeanServer--[standard JVM MBeanServer platform] . However, users might want to register these MBeans in a different MBeanServer instance. For example, an application server might work with a different MBeanServer instance to the default platform one. In such cases, users should implement the link:{javadocroot}/org/infinispan/jmx/MBeanServerLookup.html[MBeanServerLookup interface] provided by {brandname} so that the link:{javadocroot}/org/infinispan/jmx/MBeanServerLookup.html#getMBeanServer--[getMBeanServer() method] returns the MBeanServer under which {brandname} should register the management MBeans. Once you have your implementation ready, simply configure {brandname} with the fully qualified name of this class. For example:


* Via XML:

[source,xml]
----
<cache-container statistics="true">
   <jmx mbean-server-lookup="com.acme.MyMBeanServerLookup" />
</cache-container>
----


* Programmatically:

[source,java]
----
GlobalConfigurationBuilder globalConfigurationBuilder = ...
globalConfigurationBuilder.globalJmxStatistics()
    .enable()
    .mBeanServerLookup(new com.acme.MyMBeanServerLookup());

----

==== Available MBeans

For a complete list of available MBeans, refer to the link:{javadocroot}/jmxComponents.html[JMX reference documentation]

include::cli.adoc[]

=== Hawt.io
link:http://hawt.io[Hawt.io], a slick, fast, HTML5-based open source management console, also has support for {brandname}.
Refer to link:http://hawt.io/plugins/infinispan/[Hawt.io's documentation] for information regarding this plugin.

=== Writing plugins for other management tools
Any management tool that supports JMX already has basic support for {brandname}. However, custom plugins could be written to adapt the JMX information for easier consumption.
