Merge "Interim commit of metric model."

documentation/tutorials/metric_model.md

@@ -0,0 +1,124 @@
+# Introduction
+
+Prometheus is in the business of doing several things:
+
+  * exposing metrics,
+  * collecting metrics,
+  * performing computational rules upon them and generating synthetic series,
+  * triggering events based upon rule conditions, and
+  * metric series archival and deletion.
+
+The focus of this guide is oriented exclusively toward exposing metrics with
+an eye toward computational rules and event handling in the Prometheus core.
+
+After reading this guide, you will understand the following:
+
+  * what types of Prometheus metrics are available and how they work,
+  * how you should embed these metrics in your applications,
+  * what metadata you attach to them, and
+  * what to instrument.
+
+# Metric Types
+
+Prometheus offers three core metric types:
+
+  * counters,
+  * gauges, and
+  * summaries.
+
+Each is tailored toward a different purpose, so it is important to use the
+right one for the right job.
+
+## Counter
+
+A _Counter_ tracks addition or subtraction of values from itself.  It is used
+to represent state that you control and is not external.
+
+The following are good examples or applications of counters:
+
+  * pedometers: devices that track the number of steps you take,
+  * tickers: devices that measure the number of times an event has occurred,
+  * censuses: processes to count to number of individuals of a population, and
+  * _your_ bank account ledger: the sum of all transactions conducted on your
+    liquid assets.
+
+The key thing to note about _Counters_ is that they are best used when you are
+directly receiving the events that mutate their values and mutating the
+underlying values that represent their individual state.
+
+A good example is of an elevator that tracks how many times it has been used in
+its duty cycle.  Each time someone hits the button to dispatch it, the elevator
+can update its tally; and this is a tally it keeps!
+
+## Gauges
+
+A _Gauge_ reports instantaneous values based on external state.  This is
+primarily state that you do not control directly but rather that you depend on
+or can inspect.
+
+The following are good examples or applications of gauges:
+
+  * thermometer,
+  * barometer,
+  * altimeter, and
+  * total system resource utilization.
+
+Unlike a _Counter_, you don't have direct access to the events that brought the
+_Gauge_ to its value today.  This is a white-box and black-box distinction.
+
+## Which to use: Counter or Gauge?
+Knowing whether to use a _Counter_ or a _Gauge_ can be tough.  Let's perform a
+practical thought exercise.  Below is an image of an automobile's instrument
+dashboard:
+
+![Vehicle Instrument Console](dashboard.jpg "Vehicle Instrument Console")
+
+What do you see in this photo?  Take a minute to make a list.  (Don't worry;
+I'll wait for you.)
+
+From left to right and top to bottom, there are the following instruments:
+
+  * Tachometer: it measures the revolutions per minute of the engine;
+  * Clock: it measures the time;
+  * Thermometer: it measures the temperature outside the vehicle;
+  * Odometer: they measure the total miles the vehicle has traveled as well as
+    how far it has traveled on its last trip;
+  * Fuel Gauge: it measures how much fuel is in the tank;
+  * Speedometer: it measures how fast we are going.
+
+Great!  Look at this list and now think about the definitions above for
+_Counter_ and _Gauge_.  Can you identify what instruments are what?  (Again,
+I'll wait for you.)
+
+  * Tachometer: Counter.  Tricky.  The vehicle's sensors observe how quickly the
+    flywheel rotates and updates the instrument's value on frequent intervals.
+  * Clock: Gauge.  It is an external value, and we cannot watch the clock's
+    internal events.
+  * Thermometer: Gauge.  It measures an external value, and there is no way to
+    track thermodynamic events that influence the outside temperature.
+  * Odometer: Counter.  It measures distances by the number of times the
+    wheels have turned, which itself is based on an event.
+  * Fuel Gauge: Gauge.  Who would have guessed?  It uses a floating ballast and
+    a rheostat and is not event-based.
+  * Speedmeter: Counter.  Tricky.  It measures wheel rotation (events) over
+    time.
+
+## Summaries
+
+_Summary_ is a unique metric type, and one you have probably not used before.
+It samples events over sliding windows of time and provides instantaneous
+insight into their distributions, frequencies, and sums.
+
+Practically speaking, a summary collects event values and reports the
+following information:
+
+  * streaming quantile values of the entire observed population,
+  * the total sum of all observed values, and
+  * the count of events that have been observed.
+
+This is quite convenient, for if you are interested in tracking latencies of an
+operation in real time, you three types of information reported for free with
+one metric.
+
+# Acknowledgements
+Robert Bray: Vehicle Instrument Panel