feat: spec compliant metric creation and sync instruments (#2588)

.github/workflows/peer-api.yaml

@@ -27,4 +27,4 @@ jobs:
 
       - name: Check API dependency semantics (experimental)
         working-directory: experimental
-        run: lerna exec --ignore propagation-validation-server --ignore @opentelemetry/selenium-tests "node ../../../scripts/peer-api-check.js"
+        run: lerna exec --ignore propagation-validation-server --ignore @opentelemetry/selenium-tests --ignore @opentelemetry/api-metrics-wip "node ../../../scripts/peer-api-check.js"

experimental/packages/opentelemetry-api-metrics/package.json

@@ -55,6 +55,9 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
   "devDependencies": {
     "@types/mocha": "8.2.3",
     "@types/node": "14.17.33",

experimental/packages/opentelemetry-api-metrics/src/types/Meter.ts

@@ -14,14 +14,17 @@
  * limitations under the License.
  */
 
+import { CounterOptions, HistogramOptions, UpDownCounterOptions } from '..';
 import {
-  MetricOptions,
   Counter,
   Histogram,
-  ObservableGauge,
-  UpDownCounter,
   ObservableCounter,
+  ObservableCounterOptions,
+  ObservableGauge,
+  ObservableGaugeOptions,
   ObservableUpDownCounter,
+  ObservableUpDownCounterOptions,
+  UpDownCounter,
 } from './Metric';
 import { ObservableResult } from './ObservableResult';
 
@@ -48,7 +51,7 @@ export interface Meter {
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createHistogram(name: string, options?: MetricOptions): Histogram;
+  createHistogram(name: string, options?: HistogramOptions): Histogram;
 
   /**
    * Creates a new `Counter` metric. Generally, this kind of metric when the
@@ -57,7 +60,7 @@ export interface Meter {
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createCounter(name: string, options?: MetricOptions): Counter;
+  createCounter(name: string, options?: CounterOptions): Counter;
 
   /**
    * Creates a new `UpDownCounter` metric. UpDownCounter is a synchronous
@@ -76,7 +79,7 @@ export interface Meter {
    * @param name the name of the metric.
    * @param [options] the metric options.
    */
-  createUpDownCounter(name: string, options?: MetricOptions): UpDownCounter;
+  createUpDownCounter(name: string, options?: UpDownCounterOptions): UpDownCounter;
 
   /**
    * Creates a new `ObservableGauge` metric.
@@ -87,7 +90,7 @@ export interface Meter {
   createObservableGauge(
     name: string,
     callback: (observableResult: ObservableResult) => void,
-    options?: MetricOptions
+    options?: ObservableGaugeOptions
   ): ObservableGauge;
 
   /**
@@ -99,7 +102,7 @@ export interface Meter {
   createObservableCounter(
     name: string,
     callback: (observableResult: ObservableResult) => void,
-    options?: MetricOptions
+    options?: ObservableCounterOptions
   ): ObservableCounter;
 
   /**
@@ -111,6 +114,6 @@ export interface Meter {
   createObservableUpDownCounter(
     name: string,
     callback: (observableResult: ObservableResult) => void,
-    options?: MetricOptions
+    options?: ObservableUpDownCounterOptions
   ): ObservableUpDownCounter;
 }

experimental/packages/opentelemetry-api-metrics/src/types/Metric.ts

@@ -14,13 +14,12 @@
  * limitations under the License.
  */
 
+import { Context } from '@opentelemetry/api';
+
 /**
  * Options needed for metric creation
  */
 export interface MetricOptions {
-  /** The name of the component that reports the Metric. */
-  component?: string;
-
   /**
    * The description of the Metric.
    * @default ''
@@ -29,49 +28,30 @@ export interface MetricOptions {
 
   /**
    * The unit of the Metric values.
-   * @default '1'
+   * @default ''
    */
   unit?: string;
 
-  /** The map of constant attributes for the Metric. */
-  constantAttributes?: Map<string, string>;
-
-  /**
-   * Indicates the metric is a verbose metric that is disabled by default
-   * @default false
-   */
-  disabled?: boolean;
-
   /**
    * Indicates the type of the recorded value.
    * @default {@link ValueType.DOUBLE}
    */
   valueType?: ValueType;
-
-  /**
-   * Boundaries optional for histogram
-   */
-  boundaries?: number[];
-
-  /**
-   * Aggregation Temporality of metric
-   */
-  aggregationTemporality?: AggregationTemporality;
 }
 
+export type CounterOptions = MetricOptions;
+export type UpDownCounterOptions = MetricOptions;
+export type ObservableGaugeOptions = MetricOptions;
+export type ObservableCounterOptions = MetricOptions;
+export type ObservableUpDownCounterOptions = MetricOptions;
+export type HistogramOptions = MetricOptions;
+
 /** The Type of value. It describes how the data is reported. */
 export enum ValueType {
   INT,
   DOUBLE,
 }
 
-/** The kind of aggregator. */
-export enum AggregationTemporality {
-  AGGREGATION_TEMPORALITY_UNSPECIFIED,
-  AGGREGATION_TEMPORALITY_DELTA,
-  AGGREGATION_TEMPORALITY_CUMULATIVE,
-}
-
 /**
  * Counter is the most common synchronous instrument. This instrument supports
  * an `Add(increment)` function for reporting a sum, and is restricted to
@@ -91,21 +71,21 @@ export interface Counter {
   /**
    * Increment value of counter by the input. Inputs may not be negative.
    */
-  add(value: number, attributes?: Attributes): void;
+  add(value: number, attributes?: Attributes, context?: Context): void;
 }
 
 export interface UpDownCounter {
   /**
    * Increment value of counter by the input. Inputs may be negative.
    */
-  add(value: number, attributes?: Attributes): void;
+  add(value: number, attributes?: Attributes, context?: Context): void;
 }
 
 export interface Histogram {
   /**
-   * Records the given value to this histogram.
+   * Records a measurement. Value of the measurement must not be negative.
    */
-  record(value: number, attributes?: Attributes): void;
+  record(value: number, attributes?: Attributes, context?: Context): void;
 }
 
 // ObservableBase has to be an Object but for now there is no field or method

experimental/packages/opentelemetry-sdk-metrics-base/src/Meter.ts

@@ -36,19 +36,19 @@ export class Meter implements metrics.Meter {
     return this._instrumentationLibrary;
   }
 
-  createHistogram(name: string, options?: metrics.MetricOptions): Histogram {
+  createHistogram(name: string, options?: metrics.HistogramOptions): metrics.Histogram {
     const descriptor = createInstrumentDescriptor(name, InstrumentType.HISTOGRAM, options);
     const storage = this._registerMetricStorage(descriptor);
     return new Histogram(storage, descriptor);
   }
 
-  createCounter(name: string, options?: metrics.MetricOptions): metrics.Counter {
+  createCounter(name: string, options?: metrics.CounterOptions): metrics.Counter {
     const descriptor = createInstrumentDescriptor(name, InstrumentType.COUNTER, options);
     const storage = this._registerMetricStorage(descriptor);
     return new Counter(storage, descriptor);
   }
 
-  createUpDownCounter(name: string, options?: metrics.MetricOptions): metrics.UpDownCounter {
+  createUpDownCounter(name: string, options?: metrics.UpDownCounterOptions): metrics.UpDownCounter {
     const descriptor = createInstrumentDescriptor(name, InstrumentType.UP_DOWN_COUNTER, options);
     const storage = this._registerMetricStorage(descriptor);
     return new UpDownCounter(storage, descriptor);
@@ -57,24 +57,24 @@ export class Meter implements metrics.Meter {
   createObservableGauge(
     _name: string,
     _callback: (observableResult: metrics.ObservableResult) => void,
-    _options?: metrics.MetricOptions,
+    _options?: metrics.ObservableGaugeOptions,
   ): metrics.ObservableGauge {
     throw new Error('Method not implemented.');
   }
 
   createObservableCounter(
     _name: string,
     _callback: (observableResult: metrics.ObservableResult) => void,
-    _options?: metrics.MetricOptions,
-  ): metrics.ObservableBase {
+    _options?: metrics.ObservableCounterOptions,
+  ): metrics.ObservableCounter {
     throw new Error('Method not implemented.');
   }
 
   createObservableUpDownCounter(
     _name: string,
     _callback: (observableResult: metrics.ObservableResult) => void,
-    _options?: metrics.MetricOptions,
-  ): metrics.ObservableBase {
+    _options?: metrics.ObservableUpDownCounterOptions,
+  ): metrics.ObservableUpDownCounter {
     throw new Error('Method not implemented.');
   }