diff --git a/packages/opentelemetry-types/src/index.ts b/packages/opentelemetry-types/src/index.ts index 83d8e325551..f2ee2ca85db 100644 --- a/packages/opentelemetry-types/src/index.ts +++ b/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'; diff --git a/packages/opentelemetry-types/src/metrics/counter.ts b/packages/opentelemetry-types/src/metrics/counter.ts new file mode 100644 index 00000000000..069c55eec6f --- /dev/null +++ b/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; +} diff --git a/packages/opentelemetry-types/src/metrics/gauge.ts b/packages/opentelemetry-types/src/metrics/gauge.ts new file mode 100644 index 00000000000..558e7d551ca --- /dev/null +++ b/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; +} diff --git a/packages/opentelemetry-types/src/metrics/measure.ts b/packages/opentelemetry-types/src/metrics/measure.ts new file mode 100644 index 00000000000..f7217cdcf23 --- /dev/null +++ b/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 {} diff --git a/packages/opentelemetry-types/src/metrics/meter.ts b/packages/opentelemetry-types/src/metrics/meter.ts new file mode 100644 index 00000000000..e2daf15164c --- /dev/null +++ b/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; + + // 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; + + // Record a set of raw measurements. + record(measurements: Measurement[], options?: RecordOptions): void; +} diff --git a/packages/opentelemetry-types/src/metrics/metric.ts b/packages/opentelemetry-types/src/metrics/metric.ts new file mode 100644 index 00000000000..4498ba80f49 --- /dev/null +++ b/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 { + // 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; +}