| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="UTF-8"> |
| <meta http-equiv="X-UA-Compatible" content="IE=edge"> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="generator" content="Asciidoctor 2.0.18"> |
| <link rel="icon" type="image/png" href="images/favicon.png"> |
| <title>Metrics</title> |
| <link rel="stylesheet" href="css/asciidoctor.css"> |
| <link rel="stylesheet" href="css/font-awesome.css"> |
| <link rel="stylesheet" href="css/rouge-github.css"> |
| </head> |
| <body class="book toc2 toc-left"> |
| <div id="header"> |
| <h1>Metrics</h1> |
| <div id="toc" class="toc2"> |
| <div id="toctitle"><a href="index.html">User Manual for 2.33.0</a></div> |
| <ul class="sectlevel1"> |
| <li><a href="#exported-metrics">1. Exported Metrics</a> |
| <ul class="sectlevel2"> |
| <li><a href="#broker">1.1. Broker</a></li> |
| <li><a href="#address">1.2. Address</a></li> |
| <li><a href="#queue">1.3. Queue</a></li> |
| <li><a href="#optional-metrics">1.4. Optional metrics</a></li> |
| </ul> |
| </li> |
| <li><a href="#configuration">2. Configuration</a></li> |
| </ul> |
| </div> |
| </div> |
| <div id="content"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Apache ActiveMQ Artemis can export metrics to a variety of monitoring systems via the <a href="https://micrometer.io/">Micrometer</a> vendor-neutral application metrics facade.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Important runtime metrics have been instrumented via the Micrometer API, and all a user needs to do is implement <code>org.apache.activemq.artemis.core.server.metrics.ActiveMQMetricsPlugin</code> in order to instantiate and configure a <code>io.micrometer.core.instrument.MeterRegistry</code> implementation. |
| Relevant implementations of <code>MeterRegistry</code> are available from the <a href="https://github.com/micrometer-metrics/micrometer/tree/master/implementations">Micrometer code-base</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>This is a simple interface:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="java"><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">ActiveMQMetricsPlugin</span> <span class="kd">extends</span> <span class="nc">Serializable</span> <span class="o">{</span> |
| |
| <span class="nc">ActiveMQMetricsPlugin</span> <span class="nf">init</span><span class="o">(</span><span class="nc">Map</span><span class="o"><</span><span class="nc">String</span><span class="o">,</span> <span class="nc">String</span><span class="o">></span> <span class="n">options</span><span class="o">);</span> |
| |
| <span class="nc">MeterRegistry</span> <span class="nf">getRegistry</span><span class="o">();</span> |
| |
| <span class="k">default</span> <span class="kt">void</span> <span class="nf">registered</span><span class="o">(</span><span class="nc">ActiveMQServer</span> <span class="n">server</span><span class="o">)</span> <span class="o">{</span> <span class="o">}</span> |
| <span class="o">}</span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When the broker starts it will call <code>init</code> and pass in the <code>options</code> which can be specified in XML as key/value properties. |
| At this point the plugin should instantiate and configure the <code>io.micrometer.core.instrument.MeterRegistry</code> implementation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Later during the broker startup process it will call <code>getRegistry</code> in order to get the <code>MeterRegistry</code> implementation and use it for registering meters. |
| Once registered, it will call <code>registered</code> to provide the plugin with a handle to the server. |
| The plugin can then use that handle later to inspect whether the broker is operational and not in a startup or shutdown phase.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The broker ships with two <code>ActiveMQMetricsPlugin</code> implementations:</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">org.apache.activemq.artemis.core.server.metrics.plugins.LoggingMetricsPlugin</dt> |
| <dd> |
| <p>This plugin simply logs metrics. |
| It’s not very useful for production, but can serve as a demonstration of the Micrometer integration. |
| It takes no key/value properties for configuration.</p> |
| </dd> |
| <dt class="hdlist1">org.apache.activemq.artemis.core.server.metrics.plugins.SimpleMetricsPlugin</dt> |
| <dd> |
| <p>This plugin is used for testing. |
| It is in-memory only and provides no external output. |
| It takes no key/value properties for configuration.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="exported-metrics"><a class="anchor" href="#exported-metrics"></a><a class="link" href="#exported-metrics">1. Exported Metrics</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The following metrics are exported, categorized by component. |
| A description for each metric is exported along with the metric itself therefore the description will not be repeated here.</p> |
| </div> |
| <div class="sect2"> |
| <h3 id="broker"><a class="anchor" href="#broker"></a><a class="link" href="#broker">1.1. Broker</a></h3> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>connection.count</p> |
| </li> |
| <li> |
| <p>total.connection.count</p> |
| </li> |
| <li> |
| <p>address.memory.usage</p> |
| </li> |
| <li> |
| <p>address.memory.usage.percentage</p> |
| </li> |
| <li> |
| <p>disk.store.usage</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="address"><a class="anchor" href="#address"></a><a class="link" href="#address">1.2. Address</a></h3> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>routed.message.count</p> |
| </li> |
| <li> |
| <p>unrouted.message.count</p> |
| </li> |
| <li> |
| <p>address.size</p> |
| </li> |
| <li> |
| <p>number.of.pages</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="queue"><a class="anchor" href="#queue"></a><a class="link" href="#queue">1.3. Queue</a></h3> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>message.count</p> |
| </li> |
| <li> |
| <p>durable.message.count</p> |
| </li> |
| <li> |
| <p>persistent.size</p> |
| </li> |
| <li> |
| <p>durable.persistent.size</p> |
| </li> |
| <li> |
| <p>delivering.message.count</p> |
| </li> |
| <li> |
| <p>delivering.durable.message.count</p> |
| </li> |
| <li> |
| <p>delivering.persistent.size</p> |
| </li> |
| <li> |
| <p>delivering.durable.persistent.size</p> |
| </li> |
| <li> |
| <p>scheduled.message.count</p> |
| </li> |
| <li> |
| <p>scheduled.durable.message.count</p> |
| </li> |
| <li> |
| <p>scheduled.persistent.size</p> |
| </li> |
| <li> |
| <p>scheduled.durable.persistent.size</p> |
| </li> |
| <li> |
| <p>messages.acknowledged</p> |
| </li> |
| <li> |
| <p>messages.added</p> |
| </li> |
| <li> |
| <p>messages.killed</p> |
| </li> |
| <li> |
| <p>messages.expired</p> |
| </li> |
| <li> |
| <p>consumer.count</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>It may appear that some higher level broker metrics are missing (e.g. total message count). |
| However, these metrics can be deduced by aggregating the lower level metrics (e.g. aggregate the message.count metrics from all queues to get the total).</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="optional-metrics"><a class="anchor" href="#optional-metrics"></a><a class="link" href="#optional-metrics">1.4. Optional metrics</a></h3> |
| <div class="paragraph"> |
| <p>There are a handful of other useful metrics that are related to the JVM, the underlying operating system, etc.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">JVM memory metrics</dt> |
| <dd> |
| <p>Gauges buffer and memory pool utilization. |
| Underlying data gathered from Java’s <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/BufferPoolMXBean.html">BufferPoolMXBeans</a> and <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html">MemoryPoolMXBeans</a>.</p> |
| <div class="paragraph"> |
| <p>Enabled by default.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">JVM GC</dt> |
| <dd> |
| <p>Gauges max and live data size, promotion and allocation rates, and the number of times the GC pauses (or concurrent phase time in the case of CMS). |
| Underlying data gathered from Java’s <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html">MemoryPoolMXBeans</a>.</p> |
| <div class="paragraph"> |
| <p>Disabled by default.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">JVM thread</dt> |
| <dd> |
| <p>Gauges thread peak, the number of daemon threads, and live threads. |
| Underlying data gathered from Java’s <a href="https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/ThreadMXBean.html">ThreadMXBean</a>.</p> |
| <div class="paragraph"> |
| <p>Disabled by default.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Netty</dt> |
| <dd> |
| <p>Collects metrics from Netty’s <a href="https://netty.io/4.1/api/io/netty/buffer/PooledByteBufAllocatorMetric.html">PooledByteBufAllocatorMetric</a>.</p> |
| <div class="paragraph"> |
| <p>Disabled by default.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">File descriptors</dt> |
| <dd> |
| <p>Gauges current and max-allowed open files.</p> |
| <div class="paragraph"> |
| <p>Disabled by default.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Processor</dt> |
| <dd> |
| <p>Gauges system CPU count, CPU usage, and 1-minute load average as well as process CPU usage.</p> |
| <div class="paragraph"> |
| <p>Disabled by default.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Uptime</dt> |
| <dd> |
| <p>Gauges process start time and uptime.</p> |
| <div class="paragraph"> |
| <p>Disabled by default.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1">Logging</dt> |
| <dd> |
| <p>Counts the number of logging events per logging category (e.g. <code>WARN</code>, <code>ERROR</code>, etc.).</p> |
| <div class="paragraph"> |
| <p>Disabled by default.</p> |
| </div> |
| <div class="admonitionblock warning"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-warning" title="Warning"></i> |
| </td> |
| <td class="content"> |
| <div class="paragraph"> |
| <p>This works <em>exclusively</em> with Log4j2 (i.e the default logging implementation shipped with the broker). |
| If you’re embedding the broker and using a different logging implementation (e.g. Log4j 1.x, JUL, Logback, etc.) and you enable these metrics then the broker will fail to start with a <code>java.lang.NoClassDefFoundError</code> as it attempts to locate Log4j2 classes that don’t exist on the classpath.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="configuration"><a class="anchor" href="#configuration"></a><a class="link" href="#configuration">2. Configuration</a></h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Metrics for all addresses and queues are enabled by default. |
| If you want to disable metrics for a particular address or set of addresses you can do so by setting the <code>enable-metrics</code> <code>address-setting</code> to <code>false</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In <code>broker.xml</code> use the <code>metrics</code> element to configure which general broker and JVM metrics are reported and to configure the plugin itself. |
| Here’s a configuration with all optional metrics:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><metrics></span> |
| <span class="nt"><jvm-memory></span>true<span class="nt"></jvm-memory></span> <span class="c"><!-- defaults to true --></span> |
| <span class="nt"><jvm-gc></span>true<span class="nt"></jvm-gc></span> <span class="c"><!-- defaults to false --></span> |
| <span class="nt"><jvm-threads></span>true<span class="nt"></jvm-threads></span> <span class="c"><!-- defaults to false --></span> |
| <span class="nt"><netty-pool></span>true<span class="nt"></netty-pool></span> <span class="c"><!-- defaults to false --></span> |
| <span class="nt"><file-descriptors></span>true<span class="nt"></file-descriptors></span> <span class="c"><!-- defaults to false --></span> |
| <span class="nt"><processor></span>true<span class="nt"></processor></span> <span class="c"><!-- defaults to false --></span> |
| <span class="nt"><uptime></span>true<span class="nt"></uptime></span> <span class="c"><!-- defaults to false --></span> |
| <span class="nt"><logging></span>true<span class="nt"></logging></span> <span class="c"><!-- defaults to false --></span> |
| <span class="nt"><plugin</span> <span class="na">class-name=</span><span class="s">"org.apache.activemq.artemis.core.server.metrics.plugins.LoggingMetricsPlugin"</span><span class="nt">/></span> |
| <span class="nt"></metrics></span></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The plugin can also be configured with key/value properties in order to customize the implementation as necessary, e.g.:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="rouge highlight nowrap"><code data-lang="xml"><span class="nt"><metrics></span> |
| <span class="nt"><plugin</span> <span class="na">class-name=</span><span class="s">"org.example.MyMetricsPlugin"</span><span class="nt">></span> |
| <span class="nt"><property</span> <span class="na">key=</span><span class="s">"host"</span> <span class="na">value=</span><span class="s">"example.org"</span> <span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">key=</span><span class="s">"port"</span> <span class="na">value=</span><span class="s">"5162"</span> <span class="nt">/></span> |
| <span class="nt"><property</span> <span class="na">key=</span><span class="s">"foo"</span> <span class="na">value=</span><span class="s">"10"</span> <span class="nt">/></span> |
| <span class="nt"></plugin></span> |
| <span class="nt"></metrics></span></code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </body> |
| </html> |
