src/site/xdoc/server/metrics.xml - james-project - Git at Google

 <?xml version="1.0"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
 -->
 <document>

     <properties>
         <title>Apache James Server 3 - Metrics</title>
     </properties>

     <body>

         <section name="Presentation">

             <p>James relies on the <a href="https://metrics.dropwizard.io/4.1.2/manual/core.html">Dropwizard metric library</a>
             for keeping track of some core metrics of James.</p>

             <p>Such metrics are made available via JMX. You can connect for instance using VisualVM and the associated
             mbean plugins.</p>

             <p>
                 James come with native integration to the prometheus eco-system. Read below.
             </p>

             <p>
                 You can also export the metrics to ElasticSearch and visualize them with <a href="https://grafana.com/">Grafana</a>.
                 See <a href="config-elasticsearch.html">elaticseach.properties</a> documentation for more details on how to set this up.<br/>
                 <b>WARNING:</b> Supported ElasticSearch versions for metrics differs from the James one. Only ElasticSearch version 2 to 6 are supported. This requires a distinct ElasticSearch isntalation for metrics.
                 This component is furthermore unmaintained an use is discouraged.
             </p>

             <p>
                 Yet another solution is to have metrics values written in logs, see  See <a href="monitor-logging.html">Monitor via Logging</a>.
             </p>

         </section>

         <section name="Expose metrics for Prometheus collection">
             <p>To enable James metrics, add <code>extensions.routes</code> to <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/docs/modules/ROOT/pages/configure/webadmin.adoc">webadmin.properties</a> file:</p>
             <pre><code>extensions.routes=org.apache.james.webadmin.dropwizard.MetricsRoutes</code></pre>

             <p>Connect to james-admin url to test the result:</p>

             <pre><code>http://james-admin-url/metrics</code></pre>
         </section>

         <section name="Available metrics">

             <p>
                 Here are the available metrics :
                 <ul>
                     <li>James JVM metrics</li>
                     <li>Number of active SMTP connections</li>
                     <li>Number of SMTP commands received</li>
                     <li>Number of active IMAP connections</li>
                     <li>Number of IMAP commands received</li>
                     <li>Number of active LMTP connections</li>
                     <li>Number of LMTP commands received</li>
                     <li>Number of per queue number of enqueued mails</li>
                     <li>Number of sent emails</li>
                     <li>Number of delivered emails</li>
                     <li>Diverse Response time percentiles, counts and rates for JMAP</li>
                     <li>Diverse Response time percentiles, counts and rates for IMAP</li>
                     <li>Diverse Response time percentiles, counts and rates for SMTP</li>
                     <li>Diverse Response time percentiles, counts and rates for WebAdmin</li>
                     <li>Diverse Response time percentiles, counts and rates for each JMS message queue</li>
                     <li>Per mailet and per matcher Response time percentiles</li>
                     <li>Diverse Response time percentiles, counts and rates for DNS</li>
                     <li>Cassandra Java driver metrics</li>
                     <li>ActiveMQ broker/queue statistics</li>
                     <li>Tika HTTP client statistics</li>
                     <li>SpamAssassin TCP client statistics</li>
                     <li>Mailbox listeners statistics time percentiles</li>
                     <li>Mailbox listeners statistics requests rate</li>
                     <li>Pre-deletion hooks execution statistics time percentiles</li>
                 </ul>

                 Retrieve <a href="https://github.com/apache/james-project/tree/d2cf7c8e229d9ed30125871b3de5af3cb1553649/server/grafana-reporting">available boards</a> for Grafana.
             </p>

             <img src="images/performances/metrics.png"/>

             <p>
                 In addition to these metrics, you can define your own metrics using the <b>Metrics</b> mailet. By adding
                 it in your mailet container, you can count emails that pass via any points. You can also, using matchers,
                 count emails that matches the conditions you defined.
             </p>
         </section>

         <section name="Limitations">

             <p>Those metrics are only available with Guice.</p>

         </section>

     </body>

 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->
	<document>

	<properties>
	<title>Apache James Server 3 - Metrics</title>
	</properties>

	<body>

	<section name="Presentation">

	<p>James relies on the <a href="https://metrics.dropwizard.io/4.1.2/manual/core.html">Dropwizard metric library</a>
	for keeping track of some core metrics of James.</p>

	<p>Such metrics are made available via JMX. You can connect for instance using VisualVM and the associated
	mbean plugins.</p>

	<p>
	James come with native integration to the prometheus eco-system. Read below.
	</p>

	<p>
	You can also export the metrics to ElasticSearch and visualize them with <a href="https://grafana.com/">Grafana</a>.
	See <a href="config-elasticsearch.html">elaticseach.properties</a> documentation for more details on how to set this up.<br/>
	<b>WARNING:</b> Supported ElasticSearch versions for metrics differs from the James one. Only ElasticSearch version 2 to 6 are supported. This requires a distinct ElasticSearch isntalation for metrics.
	This component is furthermore unmaintained an use is discouraged.
	</p>

	<p>
	Yet another solution is to have metrics values written in logs, see See <a href="monitor-logging.html">Monitor via Logging</a>.
	</p>

	</section>

	<section name="Expose metrics for Prometheus collection">
	<p>To enable James metrics, add <code>extensions.routes</code> to <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/docs/modules/ROOT/pages/configure/webadmin.adoc">webadmin.properties</a> file:</p>
	<pre><code>extensions.routes=org.apache.james.webadmin.dropwizard.MetricsRoutes</code></pre>

	<p>Connect to james-admin url to test the result:</p>

	<pre><code>http://james-admin-url/metrics</code></pre>
	</section>

	<section name="Available metrics">

	<p>
	Here are the available metrics :
	<ul>
	<li>James JVM metrics</li>
	<li>Number of active SMTP connections</li>
	<li>Number of SMTP commands received</li>
	<li>Number of active IMAP connections</li>
	<li>Number of IMAP commands received</li>
	<li>Number of active LMTP connections</li>
	<li>Number of LMTP commands received</li>
	<li>Number of per queue number of enqueued mails</li>
	<li>Number of sent emails</li>
	<li>Number of delivered emails</li>
	<li>Diverse Response time percentiles, counts and rates for JMAP</li>
	<li>Diverse Response time percentiles, counts and rates for IMAP</li>
	<li>Diverse Response time percentiles, counts and rates for SMTP</li>
	<li>Diverse Response time percentiles, counts and rates for WebAdmin</li>
	<li>Diverse Response time percentiles, counts and rates for each JMS message queue</li>
	<li>Per mailet and per matcher Response time percentiles</li>
	<li>Diverse Response time percentiles, counts and rates for DNS</li>
	<li>Cassandra Java driver metrics</li>
	<li>ActiveMQ broker/queue statistics</li>
	<li>Tika HTTP client statistics</li>
	<li>SpamAssassin TCP client statistics</li>
	<li>Mailbox listeners statistics time percentiles</li>
	<li>Mailbox listeners statistics requests rate</li>
	<li>Pre-deletion hooks execution statistics time percentiles</li>
	</ul>

	Retrieve <a href="https://github.com/apache/james-project/tree/d2cf7c8e229d9ed30125871b3de5af3cb1553649/server/grafana-reporting">available boards</a> for Grafana.
	</p>

	<img src="images/performances/metrics.png"/>

	<p>
	In addition to these metrics, you can define your own metrics using the <b>Metrics</b> mailet. By adding
	it in your mailet container, you can count emails that pass via any points. You can also, using matchers,
	count emails that matches the conditions you defined.
	</p>
	</section>

	<section name="Limitations">

	<p>Those metrics are only available with Guice.</p>

	</section>

	</body>

	</document>