From d9acfd25ea8fc3a5e9c9f762b46494a98cdaf06a Mon Sep 17 00:00:00 2001 From: Georg Pirklbauer Date: Mon, 13 Mar 2023 15:32:36 +0100 Subject: [PATCH] Update metrics overview page (#2493) --- content/en/docs/concepts/signals/metrics.md | 38 ++++++++++++++------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/content/en/docs/concepts/signals/metrics.md b/content/en/docs/concepts/signals/metrics.md index 47412d562..127c64c73 100644 --- a/content/en/docs/concepts/signals/metrics.md +++ b/content/en/docs/concepts/signals/metrics.md @@ -14,22 +14,36 @@ indicators impact user experience or the business. Collected data can be used to alert of an outage or trigger scheduling decisions to scale up a deployment automatically upon high demand. -OpenTelemetry defines three _metric instruments_ today: +OpenTelemetry defines six _metric instruments_ today which can be created +through the OpenTelemetry API: -- **counter**: a value that is summed over time -- you can think of this like an - odometer on a car; it only ever goes up. -- **measure**: a value that is aggregated over time. This is more akin to the - trip odometer on a car, it represents a value over some defined range. -- **observer**: captures a current set of values at a particular point in time, - like a fuel gauge in a vehicle. +- **Counter**: A value that accumulates over time -- you can think of this like + an odometer on a car; it only ever goes up. +- **Asynchronous Counter**: Same as the **Counter**, but is collected once for + each export. Could be used if you don't have access to the continous + increments, but only to the aggregated value. +- **UpDownCounter**: A value that accumulates over time, but can also go down + again. An example could be a queue length, it will increase and decrease with + the number of work items in the queue. +- **Asynchronous UpDownCounter**: Same as the **UpDownCounter**, but is + collected once for each export. Could be used if you don't have access to the + continous changes, but only to the aggregated value (e.g., current queue + size). +- **(Asynchronous) Gauge**: Measures a current value at the time it is read. An + example would be the fuel gauge in a vehicle. Gauges are _always_ + asynchronous. +- **Histogram**: A histogram is a client-side aggregation of values, e.g., + request latencies. A histogram is likely a good choice if you have a lot of + values, and are not interested in every individual value, but a statistic + about these values (e.g., How many requests take fewer than 1s?) -In addition to the three metric instruments, the concept of _aggregations_ is an +In addition to the metric instruments, the concept of _aggregations_ is an important one to understand. An aggregation is a technique whereby a large number of measurements are combined into either exact or estimated statistics -about metric events that took place during a time window. The OpenTelemetry API -itself does not allow you to specify these aggregations, but provides some -default ones. In general, the OpenTelemetry SDK provides for common aggregations -(such as sum, count, last value, and histograms) that are supported by +about metric events that took place during a time window. The OTLP protocol +transports such aggreagated metrics. The OpenTelemetry API provides a default +aggregation for each instrument which can be overridden using the Views API. The +OpenTelemetry project aims to provide default aggregations that are supported by visualizers and telemetry backends. Unlike request tracing, which is intended to capture request lifecycles and