Explain the Metric API instruments

[jmacd]

This document replaces OTEPs #93 and #96.

The number of instruments is expanded to 6.

Resolves open-telemetry/opentelemetry-specification#467
Resolves open-telemetry/opentelemetry-specification#465
Resolves open-telemetry/opentelemetry-specification#462

[MrAlias]

Good start. I especially appreciate the added "Example uses" in the relevant details sections as well as the propagated table outlining the metrics.

[codeboten]

Thank you, the examples as well as explanations go a long way to clarify metric instruments in my mind. Just a few minor comments, overall it looks great!

[MikeGoldsmith]

Left some comments to fix up some links and a couple changes to language to read a little better.

[jmacd]

Thanks @MikeGoldsmith @codeboten. I found other .md files in OTel that use a syntax to avoid repeating the same link a million times, and used that for otep-88 here.

[jmacd]

There is an outstanding discussion here, #98 (comment), but it's not about the matter at hand. If we agree about the names of the instruments and their default aggregation, then I think this PR is ready to merge.

The debate above is about how we document the protocol and the internals of the SDK and export pipeline. I do not think the outcome of this debate will have an impact on the specification we write for the API. In any case we shouldn't hold this up over a decision about use of "Temporal quality" in the API documentation.

[cijothomas]

Agree the stated purpose of defining standard instrument names and their default aggregations is met!
Thanks.

[lzchen]

Really well explained! Good job!

[bogdandrutu]

@open-telemetry/specs-approvers this OTEP got very popular, can we review this to make progress?

[jmacd]

@open-telemetry/specs-approvers please approve this. We have reached agreement by all, and the only outstanding discussion point belongs to the SDK: open-telemetry/opentelemetry-proto#147

[bogdandrutu]

Please fix markdown lint errors :)

[jmacd]

@bogdandrutu Done. Needs one more approver 😆

[jmacd]

@bogdandrutu Let's merge this.

[bogdandrutu]

Yes Sir :)