<commit_before># Supplementary Guidelines

Note: this document is NOT a spec, it is provided to support the Metrics
[API](./api.md) and [SDK](./sdk.md) specifications, it does NOT add any extra
requirements to the existing specifications.

Table of Contents:

* [Guidelines for instrumentation library
  authors](#guidelines-for-instrumentation-library-authors)
* [Guidelines for SDK authors](#guidelines-for-sdk-authors)
  * [Aggregation temporality](#aggregation-temporality)
  * [Memory management](#memory-management)

## Guidelines for instrumentation library authors

TBD

## Guidelines for SDK authors

### Aggregation temporality<commit_msg>Add metrics supplementary guideline for instrumentation authors (#1981)<commit_after># Supplementary Guidelines

Note: this document is NOT a spec, it is provided to support the Metrics
[API](./api.md) and [SDK](./sdk.md) specifications, it does NOT add any extra
requirements to the existing specifications.

Table of Contents:

* [Guidelines for instrumentation library
  authors](#guidelines-for-instrumentation-library-authors)
  * [Instrument selection](#instrument-selection)
  * [Semantic convention](#semantic-convention)
* [Guidelines for SDK authors](#guidelines-for-sdk-authors)
  * [Aggregation temporality](#aggregation-temporality)
  * [Memory management](#memory-management)

## Guidelines for instrumentation library authors

### Instrument selection

The [Instruments](./api.md#instrument) are part of the [Metrics API](./api.md).
They allow [Measurements](./api.md#measurement) to be recorded
[synchronously](./api.md#synchronous-instrument) or
[asynchronously](./api.md#asynchronous-instrument).

Choosing the correct instrument is important, because:

* It helps the library to achieve better efficiency. For example, if we want to
  report room temperature to [Prometheus](https://prometheus.io), we want to
  consider using an [Asynchronous Gauge](./api.md#asynchronous-gauge) rather
  than periodically poll the sensor, so that we only access the sensor when
  scraping happened.
* It makes the consumption easier for the user of the library. For example, if
  we want to report HTTP server request latency, we want to consider a
  [Histogram](./api.md#histogram), so most of the users can get a reasonable
  experience (e.g. default buckets, min/max) by simply enabling the metrics
  stream, rather than doing extra configurations.
* It generates clarity to the semantic of the metrics stream, so the consumers
  have better understanding of the results. For example, if we want to report
  the process heap size, by using an [Asynchronous
  UpDownCounter](./api.md#asynchronous-updowncounter) rather than an
  [Asynchronous Gauge](./api.md#asynchronous-gauge), we've made it explicit that
  the consumer can add up the numbers across all processes to get the "total
  heap size".

Here is one way of choosing the correct instrument:

* I want to **count** something (by recording a delta value):
  * If the value is monotonically increasing (the delta value is always
    non-negative) - use a [Counter](./api.md#counter).
  * If the value is NOT monotonically increasing (the delta value can be
    positive, negative or zero) - use an
    [UpDownCounter](./api.md#updowncounter).
* I want to **record** or **time** something, and the **statistics** about this
  thing are likely to be meaningful - use a [Histogram](./api.md#histogram).
* I want to **measure** something (by reporting an absolute value):
  * If it makes NO sense to add up the values across different dimensions, use
    an [Asynchronous Gauge](./api.md#asynchronous-gauge).
  * If it makes sense to add up the values across different dimensions:
    * If the value is monotonically increasing - use an [Asynchronous
      Counter](./api.md#asynchronous-counter).
    * If the value is NOT monotonically increasing - use an [Asynchronous
      UpDownCounter](./api.md#asynchronous-updowncounter).

### Semantic convention

Once you decided [which instrument(s) to be used](#instrument-selection), you
will need to decide the names for the instruments and attributes.

It is highly recommended that you align with the `OpenTelemetry Semantic
Conventions`, rather than inventing your own semantics.

## Guidelines for SDK authors

### Aggregation temporality
{'fraction_non_alphanumeric': 0.09002093510118632, 'fraction_numerical': 0.0009304489416143289, 'mean_word_length': 4.740987983978638, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 1, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5994191', 'n_tokens_mistral': 1188, 'n_tokens_neox': 1117, 'n_words': 486}