Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

QI357; Started with docs on Metrics.

  • Loading branch information...
commit c12582a8b7c72b57b7f4a10d18b075829d326061 1 parent d333917
@niclash niclash authored
View
66 core/spi/src/docs/metrics.txt
@@ -0,0 +1,66 @@
+[[Metrics]]
+= Qi4j Metrics SPI =
+The Qi4j platform defines an advanced Metrics SPI to capture runtime metrics of Qi4j's internals as well be used by
+application code to provide production metrics for operations personnel, ensuring healthy state of the applications.
+
+
+== Metrics Components ==
+
+=== Gauge ===
+A Gauge is the simplest form of Metric. It is a value that the application sets, which is polled upon request. The
+application need to provide the implementation of the _value()_ method. Gauges are genericized for type-safe value
+handling.
+
+A Gauge can represent anything, for instance, thread pool levels, queue sizes and other resource allocations. It is
+useful to have separate gauges for percentage (%) and absolute numbers of the same resource. Operations are mainly
+interested in being alerted when threshold are reach as a percentage, as it is otherwise too many numbers to keep
+track of.
+
+To create a Gauge, you do something like;
+
+[snippet,java]
+--------------
+source=../test/java/org/qi4j/spi/metrics/DocumentationSupport.java
+tag=gauge
+--------------
+
+=== Counter ===
+
+[snippet,java]
+--------------
+source=../test/java/org/qi4j/spi/metrics/DocumentationSupport.java
+tag=counter
+--------------
+
+=== Histogram ===
+[snippet,java]
+--------------
+source=../test/java/org/qi4j/spi/metrics/DocumentationSupport.java
+tag=histogram
+--------------
+
+=== Meter ===
+
+[snippet,java]
+--------------
+source=../test/java/org/qi4j/spi/metrics/DocumentationSupport.java
+tag=meter
+--------------
+
+=== Timer ===
+Timers capture both the length of some execution as well as rate of calls. They can be used to time method calls, or
+critical sections, or even HTTP requests duration and similar.
+
+[snippet,java]
+--------------
+source=../test/java/org/qi4j/spi/metrics/DocumentationSupport.java
+tag=timer
+--------------
+
+=== HealthCheck ===
+
+[snippet,java]
+--------------
+source=../test/java/org/qi4j/spi/metrics/DocumentationSupport.java
+tag=healthcheck
+--------------
View
66 core/spi/src/test/java/org/qi4j/spi/metrics/DocumentationSupport.java
@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2012, Niclas Hedhman. All Rights Reserved.
+ *
+ * Licensed 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.
+ */
+
+package org.qi4j.spi.metrics;
+
+import java.util.concurrent.BlockingQueue;
+import java.util.concurrent.LinkedBlockingQueue;
+import org.qi4j.api.injection.scope.Service;
+import org.qi4j.bootstrap.Assembler;
+import org.qi4j.bootstrap.AssemblyException;
+import org.qi4j.bootstrap.ModuleAssembly;
+
+public class DocumentationSupport
+{
+ // START SNIPPET: common
+ @Service
+ private MetricsProvider provider;
+ // END SNIPPET: common
+
+ public void forDocumentationOnly()
+ {
+ // START SNIPPET: gauge
+ final BlockingQueue queue = new LinkedBlockingQueue( 20 );
+ // START SNIPPET: gauge
+ // END SNIPPET: gauge
+ MetricsGaugeFactory gaugeFactory = provider.createFactory( MetricsGaugeFactory.class );
+ MetricsGauge<Integer> gauge = gaugeFactory.registerGauge( getClass(), "Sample Gauge", new MetricsGauge<Integer>()
+ {
+ @Override
+ public Integer value()
+ {
+ return queue.size();
+ }
+ } );
+ // END SNIPPET: gauge
+
+ // START SNIPPET: counter
+ // END SNIPPET: counter
+
+ // START SNIPPET: histogram
+ // END SNIPPET: histogram
+
+ // START SNIPPET: meter
+ // END SNIPPET: meter
+
+ // START SNIPPET: timer
+ // END SNIPPET: timer
+
+ // START SNIPPET: healthcheck
+ // END SNIPPET: healthcheck
+
+ }
+}
View
21 libraries/metrics/src/docs/metrics.txt
@@ -0,0 +1,21 @@
+[[library-metrics]]
+= Qi4j Metrics =
+The Merics library is available to application code to get production metrics from their applications. It allows
+applications to easily mark critical section for metrics gathering, without handling the details with the Metrics
+Extension.
+
+There are currently the following possibilities available;
+
+ * @TimingCapture
+ * @Counting
+
+Before looking at the details of these, we need to point out that there are some pre-conditions for Metrics to be
+working. First of all, you need to install a Metrics Extensions, most likely the
+<<extension-metrics-yammer, Yammer Metrics Extension>>. See your chosen extension for details on how to do that.
+
+Once the Metrics extension is installed, you will also need a suitable backend to gather all the data out of a
+production plant and likewise a good front-end to view this. See your chosen Metrics Extension for this as well.
+
+== TimingCaptureAll ==
+There is a TimingCaptureAllConcern, which when added to a composite will install a _Timer_ for every method call
+in the composite.
Please sign in to comment.
Something went wrong with that request. Please try again.