blob: fb1c5ab0d30f3b43a3cb83b37f75a2d10663b120 [file] [log] [blame]
<!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.32.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">&lt;</span><span class="nc">String</span><span class="o">,</span> <span class="nc">String</span><span class="o">&gt;</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&#8217;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="ulist">
<ul>
<li>
<p>JVM memory metrics (exported by default)</p>
</li>
<li>
<p>JVM GC</p>
</li>
<li>
<p>JVM thread</p>
</li>
<li>
<p><a href="https://netty.io/4.1/api/io/netty/buffer/PooledByteBufAllocatorMetric.html">Netty</a></p>
</li>
<li>
<p>File descriptors</p>
</li>
<li>
<p>Processor</p>
</li>
<li>
<p>Uptime</p>
</li>
</ul>
</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 JVM metrics are reported and to configure the plugin itself.
Here&#8217;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">&lt;metrics&gt;</span>
<span class="nt">&lt;jvm-memory&gt;</span>true<span class="nt">&lt;/jvm-memory&gt;</span> <span class="c">&lt;!-- defaults to true --&gt;</span>
<span class="nt">&lt;jvm-gc&gt;</span>true<span class="nt">&lt;/jvm-gc&gt;</span> <span class="c">&lt;!-- defaults to false --&gt;</span>
<span class="nt">&lt;jvm-threads&gt;</span>true<span class="nt">&lt;/jvm-threads&gt;</span> <span class="c">&lt;!-- defaults to false --&gt;</span>
<span class="nt">&lt;netty-pool&gt;</span>true<span class="nt">&lt;/netty-pool&gt;</span> <span class="c">&lt;!-- defaults to false --&gt;</span>
<span class="nt">&lt;file-descriptors&gt;</span>true<span class="nt">&lt;/file-descriptors&gt;</span> <span class="c">&lt;!-- defaults to false --&gt;</span>
<span class="nt">&lt;processor&gt;</span>true<span class="nt">&lt;/processor&gt;</span> <span class="c">&lt;!-- defaults to false --&gt;</span>
<span class="nt">&lt;uptime&gt;</span>true<span class="nt">&lt;/uptime&gt;</span> <span class="c">&lt;!-- defaults to false --&gt;</span>
<span class="nt">&lt;plugin</span> <span class="na">class-name=</span><span class="s">"org.apache.activemq.artemis.core.server.metrics.plugins.LoggingMetricsPlugin"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;/metrics&gt;</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">&lt;metrics&gt;</span>
<span class="nt">&lt;plugin</span> <span class="na">class-name=</span><span class="s">"org.example.MyMetricsPlugin"</span><span class="nt">&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;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">/&gt;</span>
<span class="nt">&lt;/plugin&gt;</span>
<span class="nt">&lt;/metrics&gt;</span></code></pre>
</div>
</div>
</div>
</div>
</div>
</body>
</html>