Add cardinality limits to the Lightstep metrics SDK

[jmacd]

Description: This is a prototype for open-telemetry/opentelemetry-specification#2960.

This adds both InstrumentCardinalityLimit and AggregatorCardinalityLimit.

The instrument-level limit is meant as a circuit-breaker and the aggregator-level limit is a meant to allow views to correct overflow problems. Both of these features use otel.metrics.overflow=true to indicate the loss of attributes due to overflow. Only the synchronous instrument code path uses InstrumentCardinalityLimit in this PR, asynchronous do not, a low-priority issue to be solved separately. The problem is described in #410.

The aggregator-level limit is applied after view-configured filters are applied, so is useful to correct overflow problems.

The aggregator-level is treated as a hard-limit, when configured the aggregator will produce no more than the configured number of aggregations. The instrument-level limit is considered a circuit-breaker. For delta-temporality outputs, this should be set larger than the aggregator-level limit (considering inactivity periods) sufficiently to ensure that instrument-level records are recycled fast enough for dynamic cardinality changes.

Note there is a special case for overflow treatment in the async-delta output path (in viewstate); the cumulative overflow value is calculated so that the delta is correct. This is also low-priority, but as this is a prototype for an OTel specification, I considered it and tested it.

Link to tracking Issue: open-telemetry/opentelemetry-specification#1891

Testing: Detailed new tests in syncstate, viewstate.

Documentation: Added.

[codecov-commenter]

Codecov Report

Base: 87.84% // Head: 87.76% // Decreases project coverage by -0.09% ⚠️

Coverage data is based on head (f05909f) compared to base (1fb5140).
Patch coverage: 70.58% of modified lines in pull request are covered.

❗ Current head f05909f differs from pull request most recent head 02ef200. Consider uploading reports for the commit 02ef200 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #385      +/-   ##
==========================================
- Coverage   87.84%   87.76%   -0.09%     
==========================================
  Files          74       74              
  Lines        4205     4218      +13     
==========================================
+ Hits         3694     3702       +8     
- Misses        438      442       +4     
- Partials       73       74       +1     

Impacted Files	Coverage Δ
lightstep/sdk/metric/internal/syncstate/sync.go	95.02% <70.58%> (-2.60%)	⬇️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[jmacd]

open-telemetry/opentelemetry-specification#2960 (comment)

[kristinapathak]

looks great! one small comment typo.

[jmacd]

The code reviewer in me wants to suggest this could be two PRs because the two limits are independent.
The code author in me knows it was easier to put together one PR for two related changes. 👍 👎