diff --git a/documentation/tutorials/dashboard.jpg b/documentation/tutorials/dashboard.jpg new file mode 100644 index 000000000..d8f8d11af Binary files /dev/null and b/documentation/tutorials/dashboard.jpg differ diff --git a/documentation/tutorials/metric_model.md b/documentation/tutorials/metric_model.md new file mode 100644 index 000000000..336c31943 --- /dev/null +++ b/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