Adds Metrics API (open-telemetry#105)

* Adds Metrics API

https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/metrics-api.md

adds gauge and counter types

checkpoint

checkpoint

update docs

update index.ts

move todo

* yarn check

Author: bg451

packages/opentelemetry-types/src/index.ts

@@ -19,6 +19,11 @@ export * from './context/propagation/BinaryFormat';
 export * from './context/propagation/HttpTextFormat';
 export * from './distributed_context/DistributedContext';
 export * from './distributed_context/EntryValue';
+export * from './metrics/counter';
+export * from './metrics/gauge';
+export * from './metrics/measure';
+export * from './metrics/meter';
+export * from './metrics/metrics';
 export * from './resources/Resource';
 export * from './trace/attributes';
 export * from './trace/Event';

packages/opentelemetry-types/src/metrics/counter.ts

@@ -0,0 +1,23 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export interface CounterTimeseries {
+  // Adds the given value to the current value. Values cannot be negative.
+  add(value: number): void;
+
+  // Sets the given value. Value must be larger than the current recorded value.
+  set(value: number): void;
+}

packages/opentelemetry-types/src/metrics/gauge.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export interface GaugeTimeseries {
+  // Adds the given value to the current value. Values can be negative.
+  add(value: number): void;
+  // Sets the given value. Values can be negative.
+  set(value: number): void;
+}

packages/opentelemetry-types/src/metrics/measure.ts

@@ -0,0 +1,39 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export enum MeasureType {
+  DOUBLE = 0,
+  LONG = 1,
+}
+
+export interface MeasureOptions {
+  // Description of the Measure.
+  description?: string;
+
+  // Unit of the Measure.
+  unit?: string;
+
+  // Type of the Measure. Default type is DOUBLE.
+  type?: MeasureType;
+}
+
+export interface Measure {
+  // Creates a measurement with the supplied value.
+  createMeasurement(value: number): Measurement;
+}
+
+// Measurement describes an individual measurement
+export interface Measurement {}

packages/opentelemetry-types/src/metrics/meter.ts

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { SpanContext } from '../trace/span_context';
+import { DistributedContext } from '../distributed_context/DistributedContext';
+import { Measure, MeasureOptions, Measurement } from './measure';
+import { Metric, MetricOptions } from './metric';
+import { CounterTimeseries } from './counter';
+import { GaugeTimeseries } from './gauge';
+
+export interface RecordOptions {
+  // spanContext represents a measurement exemplar in the form of a SpanContext.
+  spanContext?: SpanContext;
+  // distributedContext overrides the current context and adds dimensions
+  // to the measurements.
+  distributedContext?: DistributedContext;
+}
+
+export interface Meter {
+  // Creates and returns a new @link{Measure}.
+  createMeasure(name: string, options?: MeasureOptions): Measure;
+
+  // Creates a new counter metric.
+  createCounter(
+    name: string,
+    options?: MetricOptions
+  ): Metric<CounterTimeseries>;
+
+  // TODO: Measurements can have a long or double type. However, it looks like
+  // the metric timeseries API (according to spec) accepts values instead of
+  // Measurements, meaning that if you accept a `number`, the type gets lost.
+  // Both java and csharp have gone down the route of having two gauge interfaces,
+  // GaugeDoubleTimeseries and GaugeLongTimeseries, with param for that type. It'd
+  // be cool to only have a single interface, but maybe having two is necessary?
+  // Maybe include the type as a metrics option? Probs a good gh issue, the same goes for Measure types.
+
+  // Creates a new gauge metric.
+  createGauge(name: string, options?: MetricOptions): Metric<GaugeTimeseries>;
+
+  // Record a set of raw measurements.
+  record(measurements: Measurement[], options?: RecordOptions): void;
+}

packages/opentelemetry-types/src/metrics/metric.ts

@@ -0,0 +1,63 @@
+/**
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { Attributes } from '../trace/attributes';
+import { Resource } from '../resources/Resource';
+
+export interface MetricOptions {
+  // Description of the Metric.
+  description?: string;
+
+  // Unit of the Metric values.
+  unit?: string;
+
+  // List of attribute keys with dynamic values. Order of list is important
+  // as the same order must be used when supplying values for these attributes.
+  dynamicAttributes?: string[];
+
+  // List of attributes with constant values.
+  constantAttributes?: Attributes;
+
+  // Resource the metric is associated with.
+  resource?: Resource;
+
+  // Name of the component that reports the metric.
+  component?: string;
+}
+
+// Metric represents a base class for different types of metric preaggregations.
+export interface Metric<T> {
+  // Creates a timeseries if the specified attribute values
+  // are not associated with an existing timeseries, otherwise returns the
+  // existing timeseries.
+  // Order and number of attribute values MUST match the order and number of
+  // dynanic attribute keys when the Metric was created.
+  getOrCreateTimeseries(values: unknown[]): T;
+
+  // Returns a timeseries with all attribute values not set.
+  getDefaultTimeseries(): T;
+
+  // Removes an existing timeseries. Order and number of attribute values MUST
+  // match the order and number of dynamic attribute keys when the Metric was
+  // created.
+  removesTimeseries(values: unknown[]): void;
+
+  // Clears all timeseries from the Metric.
+  clear(): void;
+
+  // todo: what should the callback signature be?
+  setCallback(fn: () => void): void;
+}