European Union / European Regional Development Fund / Investing in your future

X-Road: Operational Monitoring JMX Protocol

Technical Specification

Version: 1.1
Doc. ID: PR-OPMONJMX

Date Version Description Author
0.2 Initial version
23.01.2017 0.3 Added license text, table of contents and version history Sami Kallio
05.03.2018 0.4 Added terms and abbreviations reference and moved terms to term doc Tatu Repo
12.12.2019 1.0 Add description of serviceType gauges Ilkka Seppälä
25.06.2020 1.1 Add note about JMX being disabled by default Petteri Kivimäki

Table of Contents

License

This document is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/.

1 Introduction

This document specifies the format and protocol for exchanging health data of X-Road security servers that the X-Road operational monitoring daemon makes available for applications implementing the Java Management Extensions (JMX) using the JMX Messaging Protocol (JMXMP).

The Java Management Extensions define and architecture, the design patterns, the APIs, and the services for application and network management and monitoring in the Java programming language [JMX].

The JMX Messaging Protocol (JMXMP) connector is a configuration of the generic connector where the transport protocol is based on TCP and the object wrapping is native Java serialization [JMXMP].

In this document, the standard Managed Beans (MBeans) exposed by the operational monitoring daemon, their attributes, value types etc, are documented. The underlying protocol, error handling, authentication and encryption used in data exchange over JMXMP, are not in the scope of this document. For such details, [JMX] and [JMXMP] should be consulted.

All the sections of this specification contain normative information. All the references are normative.

This specification does not include option for partially implementing the protocol – the conformant implementation must implement the entire specification.

By default, operational monitoring JMX interface is disabled. Enabling the JMX interface is explained in [ARC-OPMOND].

1.1 Terms and Abbreviations

See X-Road terms and abbreviations documentation [TA-TERMS].

1.2 References

PR-MESS -- Cybernetica AS. X-Road: Message Protocol v4.0. Document ID: PR-MESS.
JMX -- Java Management Extensions (JMX) Specification, version 1.4, http://download.oracle.com/otn-pub/jcp/jmx_remote-1_4-mrel2-eval-spec/jsr160-jmx-1_4-mrel4-spec-FINAL-v1_0.pdf
JMXMP -- Using JMX Connectors to Manage Resources Remotely, http://docs.oracle.com/javase/8/docs/technotes/guides/jmx/overview/connectors.html
METRICS -- GitHub - dropwizard/metrics: Capturing JVM- and application-level metrics. So you know what's going on, https://github.com/dropwizard/metrics
ZABBIX -- Zabbix Documentation 3.0 - JMX monitoring, https://www.zabbix.com/documentation/3.0/manual/config/items/itemtypes/jmx_monitoring
TA-TERMS -- X-Road Terms and Abbreviations. Document ID: TA-TERMS. ARC-OPMOND -- X-Road: Operational Monitoring Daemon Architecture. Document ID: ARC-OPMOND.

2 Encoding X-Road Service Identifiers in Object Names

In the object names of exposed MBeans, X-Road service identifiers are encoded according to the following rules:

3 Objects, Attributes and Operations Exposed over JMXMP

The MBean objects exposed by the operational monitoring daemon over JMXMP have been implemented using the types of metrics available in the com.codahale.metrics library [METRICS], version 3.0. All the metric classes implement the com.codahale.metrics.Metric interface. More precisely, the following classes are used for making health data available:

For each MBean object there is an associated MBeanInfo object available that describes the management interface exposed by the object: the name of the class, the name of the object and its description for consumers of the data over JMXMP.

3.1 Gauge Metrics

The value of the ClassName attribute of the MBeanInfo object for gauges is com.codahale.metrics.JmxReporter$JmxGauge.

All gauge metrics expose the Value attribute and the objectName()operation over JMXMP.

The operational monitoring daemon provides the following general gauges:

For each service mediated during the configured statistics period, the following gauges are provided:

where <service ID> will be replaced by the full ID of the service encoded as described in [Section 2].

3.2 Counter Metrics

The value of the ClassName attribute of the MBeanInfo object for counters is com.codahale.metrics.JmxReporter$JmxCounter.

All counter metrics expose the Count attribute and the objectName()operation over JMXMP.

For each service mediated during the configured statistics period, the following counters are provided:

where <service ID> will be replaced by the full ID of the service encoded as described in [Section 2.

3.3 Histogram Metrics

The value of the ClassName attribute of the MBeanInfo object for histograms is com.codahale.metrics.JmxReporter$JmxHistogram.

All the histogram metrics expose the following attributes:

The operations exposed by histogram metrics are objectName() and values().

For each service mediated during the configured statistics period, the following histograms are provided:

where <service ID> will be replaced by the full ID of the service encoded as described in [Section 2].