|
1 | 1 | opentelemetry_api_experimental |
2 | 2 | ===== |
3 | 3 |
|
4 | | -An OTP library |
| 4 | +Signals still in experimental status in the Erlang/Elixir API. |
5 | 5 |
|
6 | | -Build |
7 | | ------ |
| 6 | +# Metrics |
8 | 7 |
|
9 | | - $ rebar3 compile |
| 8 | +For configuration of the Experimental SDK for Metrics see the experimental SDK |
| 9 | +`opentelemtry_experimental`. Without the SDK all operations for instruments and |
| 10 | +recording to them will be no-ops and nothing will be created or exported. |
| 11 | + |
| 12 | +## Quickstart |
| 13 | + |
| 14 | +The metrics API is used for instrumenting application code through the creation |
| 15 | +of instruments and calls to record data points with them. |
| 16 | + |
| 17 | +### Instrument Creation |
| 18 | + |
| 19 | +#### Supported Instruments |
| 20 | + |
| 21 | +There are 3 synchronous instrument types and 3 observable instruments that are |
| 22 | +tied to a callback function. The list below gives each instrument type supported |
| 23 | +and details on the default aggregation used for the measurements recorded for |
| 24 | +that instrument: |
| 25 | + |
| 26 | +- Counter: An always increasing value. |
| 27 | +- Updown Counter: A non-monotonic counter. |
| 28 | +- Histogram: A histogram with explicit bucket boundaries. |
| 29 | +- Observable Counter: A counter that is tied to a callback for recording measurements. |
| 30 | +- Observable Updown Counter: An updown counter that is tied to a callback for recording measurements. |
| 31 | +- Observable Gauge: An instrument tied to a callback who's default aggregated |
| 32 | + value is the last value recorded by the last call of the callback. |
| 33 | + |
| 34 | +#### Macros |
| 35 | + |
| 36 | +The header `otel_meter.hrl` contains macros for working with Instruments. This |
| 37 | +includes creation in the form `create_<instrument type>` and recording |
| 38 | +measurements like `counter_add` and `histogram_record`. |
| 39 | + |
| 40 | +Below is example creation found in the [`dice_roll_elli` |
| 41 | +example](https://github.com/open-telemetry/opentelemetry-erlang-contrib/tree/main/examples/roll_dice_elli): |
| 42 | + |
| 43 | +```erlang |
| 44 | +-include_lib("opentelemetry_api_experimental/include/otel_meter.hrl"). |
| 45 | + |
| 46 | +?create_counter(?ROLL_COUNTER, #{description => <<"The number of rolls by roll value.">>, |
| 47 | + unit => '1'}). |
| 48 | +``` |
| 49 | +### Instrument Recording |
| 50 | + |
| 51 | +Measurements are taken on an instrument through recordings. Each type of |
| 52 | +instrument has functions and macros specific to its type for recording |
| 53 | +measurements. Counters can be added to so have the `counter_add` macro, UpDown |
| 54 | +counters can also be added to (but with the addition of accepting negative |
| 55 | +numbers) so have `updown_counter_add` and Histograms are passed recordings so |
| 56 | +have the macro `histogram_record`. |
| 57 | + |
| 58 | + |
| 59 | +An example from [`dice_roll_elli` |
| 60 | +example](https://github.com/open-telemetry/opentelemetry-erlang-contrib/tree/main/examples/roll_dice_elli) |
| 61 | +of recording an addition to a counter with an attribute: |
| 62 | + |
| 63 | +```erlang |
| 64 | +?counter_add(?ROLL_COUNTER, 1, #{'roll.value' => Roll}), |
| 65 | +``` |
| 66 | + |
| 67 | +See the Experimental SDK's `README.md` for how to setup Views for aggregation |
| 68 | +and then the exporting of metrics. |
| 69 | + |
| 70 | +## Details |
| 71 | + |
| 72 | +### Meter Provider |
| 73 | + |
| 74 | +The Meter Provider (here the default implementation is in the module |
| 75 | +`otel_meter_server` in the SDK) is responsible for creating Meters and stores |
| 76 | +their shared configuration along with the shared |
| 77 | +[Resource](https://opentelemetry.io/docs/concepts/resources/) of the telemetry |
| 78 | +created for those Meters. Including the SDK application ensures a default |
| 79 | +Provider is created and used during Meter creation. |
| 80 | + |
| 81 | +### Meter |
| 82 | + |
| 83 | +Meters (default implementation found in `otel_meter_default` in the SDK) are |
| 84 | +used to create Instruments. Direct interaction with a Meter is not required |
| 85 | +except for special cases where the provided macros aren't enough to get the job |
| 86 | +done. The majority of use is done behind the macros. |
| 87 | + |
| 88 | +### Measurement |
| 89 | + |
| 90 | +Measurements are individual data points and their associated attributes. |
| 91 | + |
| 92 | +### Instrument |
| 93 | + |
| 94 | +An instrument is used to capture measurements. |
| 95 | + |
| 96 | +Supported instrument kinds: |
| 97 | + |
| 98 | +- Counter: Defaults to using a monotonic sum aggregation type in the SDK. |
| 99 | +- Updown Counter: Defaults to a non-monotonic sum aggregation type in the SDK. |
| 100 | +- Histogram: Defaults to an explicit histogram aggregation type in the SDK. |
| 101 | +- Observable Counter: Defaults to using a monotonic sum aggregation type in the SDK. |
| 102 | +- Observable Updown counter: Defaults to a non-monotonic sum aggregation type in the SDK. |
| 103 | +- Observable Gauge: Defaults to a last value aggregation type in the SDK. |
| 104 | + |
| 105 | +The first 3 are synchronous instruments while the latter 3 must be associated |
| 106 | +with a callback function. |
| 107 | + |
| 108 | +To record measurements an instrument must first be created. Each instrument kind |
| 109 | +has a `?create_<kind>` macro in Erlang for creation: |
| 110 | + |
| 111 | +```erlang |
| 112 | +_RequestCounter = ?create_counter(app_request_counter, #{description => ~"Count of number of requests"}) |
| 113 | +``` |
| 114 | + |
| 115 | +Now the instrument can be used to record measurements either by passing the |
| 116 | +atom name `app_request_counter`: |
| 117 | + |
| 118 | +```erlang |
| 119 | +?counter_add(app_request_counter, 5, #{<<"a">> => <<"b">>}), |
| 120 | +``` |
| 121 | + |
| 122 | +For synchronous instruments the available macros are: |
| 123 | + |
| 124 | +- `?counter_add(Name, Number, Attributes)` |
| 125 | +- `?updown_counter_add(Name, Number, Attributes)` |
| 126 | +- `?histogram_record(Name, Number, Attributes)` |
| 127 | + |
| 128 | +The asynchronous (observable) instruments can be created with their callback or |
| 129 | +be later registered with a callback that supports multiple instruments. |
| 130 | + |
| 131 | +When created with a callback for the instrument the callback returns a list of |
| 132 | +values and attributes to record for that instrument: |
| 133 | + |
| 134 | +```erlang |
| 135 | +?create_observable_counter(my_observable_counter, |
| 136 | + fun(_Args) -> |
| 137 | + [{4, #{a => <<"b">>}}, |
| 138 | + {12, #{c => <<"d">>}] |
| 139 | + end, |
| 140 | + [], |
| 141 | + #{description => <<"Describe your instrument">>, |
| 142 | + unit => kb}) |
| 143 | +``` |
| 144 | + |
| 145 | +When the measurements are taken from the same source it is more efficient to |
| 146 | +create a single callback for multiple instruments: |
| 147 | + |
| 148 | +```erlang |
| 149 | +ProcessCountName = 'beam_processes', |
| 150 | +AtomCountName = 'beam_atoms', |
| 151 | + |
| 152 | +ProcessGauge = ?create_observable_gauge(ProcessCountName, #{description => <<"Number of currently running processes">>, unit => '1'}), |
| 153 | +AtomGauge = ?create_observable_gauge(AtomCountName, #{description => <<"Number of created atoms">>, unit => '1'}), |
| 154 | + |
| 155 | +?register_callback([ProcessGauge, AtomGauge], |
| 156 | + fun(_) -> |
| 157 | + ProcessCount = erlang:system_info(process_count), |
| 158 | + AtomCount = erlang:system_info(atom_count), |
| 159 | + [{ProcessCountName, [{ProcessCount, #{}}]}, |
| 160 | + {AtomCountName, [{AtomCount, #{}}]}] |
| 161 | + end, []) |
| 162 | +``` |
| 163 | + |
| 164 | +The callbacks are run when the Metric Reader collects metrics for export. See |
| 165 | +the Experimental SDK's `README.md` for more details on Metric Readers and their |
| 166 | +configuration. |
0 commit comments