diff --git a/packages/opentelemetry-types/src/index.ts b/packages/opentelemetry-types/src/index.ts index f2ee2ca85d..473e6f358a 100644 --- a/packages/opentelemetry-types/src/index.ts +++ b/packages/opentelemetry-types/src/index.ts @@ -19,11 +19,10 @@ 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 './metrics/Handle'; +export * from './metrics/Measure'; +export * from './metrics/Meter'; +export * from './metrics/Metric'; export * from './resources/Resource'; export * from './trace/attributes'; export * from './trace/Event'; diff --git a/packages/opentelemetry-types/src/metrics/counter.ts b/packages/opentelemetry-types/src/metrics/Handle.ts similarity index 52% rename from packages/opentelemetry-types/src/metrics/counter.ts rename to packages/opentelemetry-types/src/metrics/Handle.ts index 069c55eec6..60a3a32875 100644 --- a/packages/opentelemetry-types/src/metrics/counter.ts +++ b/packages/opentelemetry-types/src/metrics/Handle.ts @@ -14,10 +14,32 @@ * limitations under the License. */ -export interface CounterTimeseries { - // Adds the given value to the current value. Values cannot be negative. +/** A Handle for Counter Metric. */ +export interface CounterHandle { + /** + * Adds the given value to the current value. Values cannot be negative. + * @param value the value to add + */ add(value: number): void; - // Sets the given value. Value must be larger than the current recorded value. + /** + * Sets the given value. Value must be larger than the current recorded value. + * @param value the new value. + */ + set(value: number): void; +} + +/** A Handle for Gauge Metric. */ +export interface GaugeHandle { + /** + * Adds the given value to the current value. Values can be negative. + * @param value the value to add. + */ + add(value: number): void; + + /** + * Sets the given value. Values can be negative. + * @param value the new value. + */ set(value: number): void; } diff --git a/packages/opentelemetry-types/src/metrics/measure.ts b/packages/opentelemetry-types/src/metrics/Measure.ts similarity index 54% rename from packages/opentelemetry-types/src/metrics/measure.ts rename to packages/opentelemetry-types/src/metrics/Measure.ts index f7217cdcf2..e67c11b4d6 100644 --- a/packages/opentelemetry-types/src/metrics/measure.ts +++ b/packages/opentelemetry-types/src/metrics/Measure.ts @@ -14,11 +14,17 @@ * limitations under the License. */ +import { DistributedContext } from '../distributed_context/DistributedContext'; +import { SpanContext } from '../trace/span_context'; + export enum MeasureType { DOUBLE = 0, LONG = 1, } +/** + * Options needed for measure creation + */ export interface MeasureOptions { // Description of the Measure. description?: string; @@ -30,10 +36,20 @@ export interface MeasureOptions { type?: MeasureType; } +/** Measure to report instantaneous measurement of a value. */ export interface Measure { - // Creates a measurement with the supplied value. - createMeasurement(value: number): Measurement; + /** + * Records the given value to this measure. + * @param value the measurement to record. + * @param distContext the distContext associated with the measurements. + * @param spanContext the {@link SpanContext} that identifies the {@link Span} + * for which the measurements are associated with. + */ + record(value: number): void; + record(value: number, distContext: DistributedContext): void; + record( + value: number, + distContext: DistributedContext, + spanContext: SpanContext + ): void; } - -// Measurement describes an individual measurement -export interface Measurement {} diff --git a/packages/opentelemetry-types/src/metrics/meter.ts b/packages/opentelemetry-types/src/metrics/Meter.ts similarity index 58% rename from packages/opentelemetry-types/src/metrics/meter.ts rename to packages/opentelemetry-types/src/metrics/Meter.ts index e2daf15164..170467a408 100644 --- a/packages/opentelemetry-types/src/metrics/meter.ts +++ b/packages/opentelemetry-types/src/metrics/Meter.ts @@ -14,30 +14,31 @@ * 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; -} +import { Metric, MetricOptions } from './Metric'; +import { CounterHandle, GaugeHandle } from './Handle'; +import { MeasureOptions, Measure } from './Measure'; +/** + * An interface to allow the recording metrics. + * + * {@link Metric}s are used for recording pre-defined aggregation (Gauge and + * Counter), or raw values ({@link Measure}) in which the aggregation and labels + * for the exported metric are deferred. + */ export interface Meter { - // Creates and returns a new @link{Measure}. + /** + * Creates and returns a new {@link Measure}. + * @param name the name of the metric. + * @param [options] the measure options. + */ createMeasure(name: string, options?: MeasureOptions): Measure; - // Creates a new counter metric. - createCounter( - name: string, - options?: MetricOptions - ): Metric; + /** + * Creates a new counter metric. + * @param name the name of the metric. + * @param [options] the metric options. + */ + createCounter(name: string, options?: MetricOptions): Metric; // TODO: Measurements can have a long or double type. However, it looks like // the metric timeseries API (according to spec) accepts values instead of @@ -47,9 +48,10 @@ export interface Meter { // 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; - - // Record a set of raw measurements. - record(measurements: Measurement[], options?: RecordOptions): void; + /** + * Creates a new gauge metric. + * @param name the name of the metric. + * @param [options] the metric options. + */ + createGauge(name: string, options?: MetricOptions): Metric; } diff --git a/packages/opentelemetry-types/src/metrics/Metric.ts b/packages/opentelemetry-types/src/metrics/Metric.ts new file mode 100644 index 0000000000..41ee9c8f21 --- /dev/null +++ b/packages/opentelemetry-types/src/metrics/Metric.ts @@ -0,0 +1,75 @@ +/** + * 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 { Resource } from '../resources/Resource'; + +/** + * Options needed for metric creation + */ +export interface MetricOptions { + /** The description of the Metric. */ + description?: string; + + /** The unit of the Metric values. */ + unit?: string; + + /** The list of label keys for the Metric. */ + labelKeys?: string[]; + + /** The map of constant labels for the Metric. */ + constantLabels?: Map; + + /** The resource the Metric is associated with. */ + resource?: Resource; + + /** The name of the component that reports the Metric. */ + component?: string; +} + +/** + * Metric represents a base class for different types of metric + * pre aggregations. + */ +export interface Metric { + /** + * Returns a Handle associated with specified label values. + * It is recommended to keep a reference to the Handle instead of always + * calling this method for every operations. + * @param labelValues the list of label values. + */ + getHandle(labelValues: string[]): T; + + /** + * Returns a Handle for a metric with all labels not set. + */ + getDefaultHandle(): T; + + /** + * Removes the Handle from the metric, if it is present. + * @param labelValues the list of label values. + */ + removeHandle(labelValues: string[]): void; + + /** + * Clears all timeseries from the Metric. + */ + clear(): void; + + /** + * what should the callback signature be? + */ + setCallback(fn: () => void): void; +} diff --git a/packages/opentelemetry-types/src/metrics/gauge.ts b/packages/opentelemetry-types/src/metrics/gauge.ts deleted file mode 100644 index 558e7d551c..0000000000 --- a/packages/opentelemetry-types/src/metrics/gauge.ts +++ /dev/null @@ -1,22 +0,0 @@ -/** - * 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; -} diff --git a/packages/opentelemetry-types/src/metrics/metric.ts b/packages/opentelemetry-types/src/metrics/metric.ts deleted file mode 100644 index 4498ba80f4..0000000000 --- a/packages/opentelemetry-types/src/metrics/metric.ts +++ /dev/null @@ -1,63 +0,0 @@ -/** - * 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 { - // 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; -}