[sdk-metrics] clarify interface to show that Aggregation is not user-implementable

[pichlermarc]

Description

For users the nature of the Aggregation class can be confusing, as it seems like it should be user-implementable but it actually is not as the needed types are not exported (see #4616). The concept of user-implementable Aggregations is called an Aggregator and this term is currently reserved for a future spec:

Note: the term aggregation is used instead of aggregator. It is RECOMMENDED that implementors reserve the “aggregator” term for the future when the SDK allows custom aggregation implementations.

To avoid confusion we should change the public interface of View to take an aggregation descriptor. Instead of creating and referencing an Aggregation instance directly, we can replace it with a enum that designates the type, as well as the options which can be part of the aggregation descriptor passed to the View. We can then use these descriptors to instantiate Aggregations internally.

Example: Drop Aggregation

Before:

const dropView = new View({
  aggregation: new DropAggregation(),
  meterName: 'pubsub',
});

After:

const dropView = new View({
  aggregation: { type: AggregationType.DROP },
  meterName: 'pubsub',
});

Example: Explicit Bucket Histogram Aggregation

Before:

const histogramView = new View({
  aggregation: new ExplicitBucketHistogramAggregation([
    0, 1, 5, 10, 15, 20, 25, 30,
  ]),
  instrumentName: 'http.server.duration',
  instrumentType: InstrumentType.HISTOGRAM,
});

After:

const histogramView = new View({
  aggregation: {
    type: AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
    boundaries: [0, 1, 5, 10, 15, 20, 25, 30]
  },
  instrumentName: 'http.server.duration',
  instrumentType: InstrumentType.HISTOGRAM,
});

Tasks:

• replace the ViewOptions.aggregation property's type with a type similar to what's described in the examples above, instantiate all Aggregations internally
• remove all mentions of Aggregation from the public interface, ensure that Aggregation is not exported from the @opentelemtry/sdk-metrics package.

[github-actions]

This issue is stale because it has been open 60 days with no activity. Remove stale label or comment or this will be closed in 14 days.

[david-luna]

@pichlermarc is there anything else to do?

[pichlermarc]

@david-luna nothing to do anymore, thanks for the reminder - I thought I had linked that PR properly. 🙂