diff --git a/README.md b/README.md index 074a0ec2..ff7a382b 100644 --- a/README.md +++ b/README.md @@ -107,8 +107,10 @@ Because the npm installer and node module resolution algorithm could potentially ### 1.0.0-rc.0 to x +- Removing `TimedEvent` which was not part of spec - `HttpBaggage` renamed to `HttpBaggagePropagator` - [#45](https://github.com/open-telemetry/opentelemetry-js-api/pull/45) `Span#context` renamed to `Span#spanContext` +- [#47](https://github.com/open-telemetry/opentelemetry-js-api/pull/47) `getSpan`/`setSpan`/`getSpanContext`/`setSpanContext` moved to `trace` namespace ## Useful links diff --git a/package.json b/package.json index 6fff6ef9..bd1ea0d0 100644 --- a/package.json +++ b/package.json @@ -55,14 +55,14 @@ "access": "public" }, "devDependencies": { - "@types/mocha": "8.2.1", - "@types/node": "14.14.28", - "@types/sinon": "9.0.10", + "@types/mocha": "8.2.2", + "@types/node": "14.14.42", + "@types/sinon": "10.0.0", "@types/webpack-env": "1.16.0", - "@typescript-eslint/eslint-plugin": "4.15.1", - "@typescript-eslint/parser": "4.15.1", + "@typescript-eslint/eslint-plugin": "4.22.0", + "@typescript-eslint/parser": "4.22.0", "codecov": "3.8.1", - "eslint": "7.20.0", + "eslint": "7.25.0", "eslint-plugin-header": "3.1.1", "eslint-plugin-import": "2.22.1", "gh-pages": "3.1.0", @@ -74,15 +74,15 @@ "karma-mocha": "2.0.1", "karma-spec-reporter": "0.0.32", "karma-webpack": "4.0.2", - "lerna-changelog": "^1.0.1", - "linkinator": "2.13.5", + "lerna-changelog": "1.0.1", + "linkinator": "2.13.6", "mocha": "7.2.0", "nyc": "15.1.0", - "sinon": "9.2.4", - "ts-loader": "8.0.17", + "sinon": "10.0.0", + "ts-loader": "8.2.0", "ts-mocha": "8.0.0", - "typedoc": "0.20.25", - "typescript": "4.1.5", + "typedoc": "0.20.36", + "typescript": "4.2.4", "webpack": "4.46.0" } } diff --git a/src/api/trace.ts b/src/api/trace.ts index f2f083af..f44fe256 100644 --- a/src/api/trace.ts +++ b/src/api/trace.ts @@ -14,15 +14,24 @@ * limitations under the License. */ -import { ProxyTracerProvider } from '../trace/ProxyTracerProvider'; -import { Tracer } from '../trace/tracer'; -import { TracerProvider } from '../trace/tracer_provider'; -import { isSpanContextValid } from '../trace/spancontext-utils'; import { getGlobal, registerGlobal, unregisterGlobal, } from '../internal/global-utils'; +import { ProxyTracerProvider } from '../trace/ProxyTracerProvider'; +import { + isSpanContextValid, + wrapSpanContext, +} from '../trace/spancontext-utils'; +import { Tracer } from '../trace/tracer'; +import { TracerProvider } from '../trace/tracer_provider'; +import { + getSpan, + getSpanContext, + setSpan, + setSpanContext, +} from '../trace/context-utils'; const API_NAME = 'trace'; @@ -76,5 +85,15 @@ export class TraceAPI { this._proxyTracerProvider = new ProxyTracerProvider(); } + public wrapSpanContext = wrapSpanContext; + public isSpanContextValid = isSpanContextValid; + + public getSpan = getSpan; + + public getSpanContext = getSpanContext; + + public setSpan = setSpan; + + public setSpanContext = setSpanContext; } diff --git a/src/baggage/index.ts b/src/baggage/index.ts index ba0a297c..03eda420 100644 --- a/src/baggage/index.ts +++ b/src/baggage/index.ts @@ -18,10 +18,17 @@ import { Baggage } from './Baggage'; import { BaggageEntry, BaggageEntryMetadata } from './Entry'; import { BaggageImpl } from './internal/baggage'; import { baggageEntryMetadataSymbol } from './internal/symbol'; +import { Context } from '../context/types'; +import { createContextKey } from '../context/context'; export * from './Baggage'; export * from './Entry'; +/** + * Baggage key + */ +const BAGGAGE_KEY = createContextKey('OpenTelemetry Baggage Key'); + /** * Create a new Baggage with optional entries * @@ -33,6 +40,22 @@ export function createBaggage( return new BaggageImpl(new Map(Object.entries(entries))); } +/** + * @param {Context} Context that manage all context values + * @returns {Baggage} Extracted baggage from the context + */ +export function getBaggage(context: Context): Baggage | undefined { + return (context.getValue(BAGGAGE_KEY) as Baggage) || undefined; +} + +/** + * @param {Context} Context that manage all context values + * @param {Baggage} baggage that will be set in the actual context + */ +export function setBaggage(context: Context, baggage: Baggage): Context { + return context.setValue(BAGGAGE_KEY, baggage); +} + /** * Create a serializable BaggageEntryMetadata object from a string. * diff --git a/src/context/context.ts b/src/context/context.ts index f6a87ba4..825726f3 100644 --- a/src/context/context.ts +++ b/src/context/context.ts @@ -15,114 +15,6 @@ */ import { Context } from './types'; -import { Baggage, Span, SpanContext } from '../'; -import { NonRecordingSpan } from '../trace/NonRecordingSpan'; - -/** - * span key - */ -const SPAN_KEY = createContextKey('OpenTelemetry Context Key SPAN'); - -/** - * Shared key for indicating if instrumentation should be suppressed beyond - * this current scope. - */ -const SUPPRESS_INSTRUMENTATION_KEY = createContextKey( - 'OpenTelemetry Context Key SUPPRESS_INSTRUMENTATION' -); - -/** - * Baggage key - */ -const BAGGAGE_KEY = createContextKey('OpenTelemetry Baggage Key'); - -/** - * Return the span if one exists - * - * @param context context to get span from - */ -export function getSpan(context: Context): Span | undefined { - return (context.getValue(SPAN_KEY) as Span) || undefined; -} - -/** - * Set the span on a context - * - * @param context context to use as parent - * @param span span to set active - */ -export function setSpan(context: Context, span: Span): Context { - return context.setValue(SPAN_KEY, span); -} - -/** - * Wrap span context in a NonRecordingSpan and set as span in a new - * context - * - * @param context context to set active span on - * @param spanContext span context to be wrapped - */ -export function setSpanContext( - context: Context, - spanContext: SpanContext -): Context { - return setSpan(context, new NonRecordingSpan(spanContext)); -} - -/** - * Get the span context of the span if it exists. - * - * @param context context to get values from - */ -export function getSpanContext(context: Context): SpanContext | undefined { - return getSpan(context)?.spanContext(); -} - -/** - * Sets value on context to indicate that instrumentation should - * be suppressed beyond this current scope. - * - * @param context context to set the suppress instrumentation value on. - */ -export function suppressInstrumentation(context: Context): Context { - return context.setValue(SUPPRESS_INSTRUMENTATION_KEY, true); -} - -/** - * Sets value on context to indicate that instrumentation should - * no-longer be suppressed beyond this current scope. - * - * @param context context to set the suppress instrumentation value on. - */ -export function unsuppressInstrumentation(context: Context): Context { - return context.setValue(SUPPRESS_INSTRUMENTATION_KEY, false); -} - -/** - * Return current suppress instrumentation value for the given context, - * if it exists. - * - * @param context context check for the suppress instrumentation value. - */ -export function isInstrumentationSuppressed(context: Context): boolean { - return Boolean(context.getValue(SUPPRESS_INSTRUMENTATION_KEY)); -} - -/** - * @param {Context} Context that manage all context values - * @returns {Baggage} Extracted baggage from the context - */ -export function getBaggage(context: Context): Baggage | undefined { - return (context.getValue(BAGGAGE_KEY) as Baggage) || undefined; -} - -/** - * @param {Context} Context that manage all context values - * @param {Baggage} baggage that will be set in the actual context - */ -export function setBaggage(context: Context, baggage: Baggage): Context { - return context.setValue(BAGGAGE_KEY, baggage); -} /** Get a key to uniquely identify a context value */ export function createContextKey(description: string) { diff --git a/src/index.ts b/src/index.ts index b36eaccd..34931412 100644 --- a/src/index.ts +++ b/src/index.ts @@ -21,8 +21,6 @@ export * from './diag'; export * from './propagation/NoopTextMapPropagator'; export * from './propagation/TextMapPropagator'; export * from './trace/attributes'; -export * from './trace/Event'; -export * from './trace/link_context'; export * from './trace/link'; export * from './trace/NoopTracer'; export * from './trace/NoopTracerProvider'; @@ -35,7 +33,6 @@ export * from './trace/span_kind'; export * from './trace/span'; export * from './trace/SpanOptions'; export * from './trace/status'; -export * from './trace/TimedEvent'; export * from './trace/trace_flags'; export * from './trace/trace_state'; export * from './trace/tracer_provider'; diff --git a/src/trace/Event.ts b/src/trace/Event.ts deleted file mode 100644 index 8bc5e274..00000000 --- a/src/trace/Event.ts +++ /dev/null @@ -1,25 +0,0 @@ -/* - * Copyright The 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 { SpanAttributes } from './attributes'; - -/** A text annotation with a set of attributes. */ -export interface Event { - /** The name of the event. */ - name: string; - /** The attributes of the event. */ - attributes?: SpanAttributes; -} diff --git a/src/trace/NoopTracer.ts b/src/trace/NoopTracer.ts index 1fbaf869..67eac54f 100644 --- a/src/trace/NoopTracer.ts +++ b/src/trace/NoopTracer.ts @@ -14,7 +14,7 @@ * limitations under the License. */ -import { getSpanContext } from '../context/context'; +import { getSpanContext } from '../trace/context-utils'; import { Context } from '../context/types'; import { NonRecordingSpan } from './NonRecordingSpan'; import { Span } from './span'; diff --git a/src/trace/TimedEvent.ts b/src/trace/TimedEvent.ts deleted file mode 100644 index 632107b2..00000000 --- a/src/trace/TimedEvent.ts +++ /dev/null @@ -1,26 +0,0 @@ -/* - * Copyright The 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 { Event } from './Event'; -import { HrTime } from '../common/Time'; - -/** - * Represents a timed event. - * A timed event is an event with a timestamp. - */ -export interface TimedEvent extends Event { - time: HrTime; -} diff --git a/src/trace/context-utils.ts b/src/trace/context-utils.ts new file mode 100644 index 00000000..4d8d2fe8 --- /dev/null +++ b/src/trace/context-utils.ts @@ -0,0 +1,106 @@ +/* + * Copyright The 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 { createContextKey } from '../context/context'; +import { Context } from '../context/types'; +import { Span } from './span'; +import { SpanContext } from './span_context'; +import { NonRecordingSpan } from './NonRecordingSpan'; + +/** + * span key + */ +const SPAN_KEY = createContextKey('OpenTelemetry Context Key SPAN'); + +/** + * Shared key for indicating if instrumentation should be suppressed beyond + * this current scope. + */ +const SUPPRESS_INSTRUMENTATION_KEY = createContextKey( + 'OpenTelemetry Context Key SUPPRESS_INSTRUMENTATION' +); + +/** + * Return the span if one exists + * + * @param context context to get span from + */ +export function getSpan(context: Context): Span | undefined { + return (context.getValue(SPAN_KEY) as Span) || undefined; +} + +/** + * Set the span on a context + * + * @param context context to use as parent + * @param span span to set active + */ +export function setSpan(context: Context, span: Span): Context { + return context.setValue(SPAN_KEY, span); +} + +/** + * Wrap span context in a NoopSpan and set as span in a new + * context + * + * @param context context to set active span on + * @param spanContext span context to be wrapped + */ +export function setSpanContext( + context: Context, + spanContext: SpanContext +): Context { + return setSpan(context, new NonRecordingSpan(spanContext)); +} + +/** + * Get the span context of the span if it exists. + * + * @param context context to get values from + */ +export function getSpanContext(context: Context): SpanContext | undefined { + return getSpan(context)?.spanContext(); +} + +/** + * Sets value on context to indicate that instrumentation should + * be suppressed beyond this current scope. + * + * @param context context to set the suppress instrumentation value on. + */ +export function suppressInstrumentation(context: Context): Context { + return context.setValue(SUPPRESS_INSTRUMENTATION_KEY, true); +} + +/** + * Sets value on context to indicate that instrumentation should + * no-longer be suppressed beyond this current scope. + * + * @param context context to set the suppress instrumentation value on. + */ +export function unsuppressInstrumentation(context: Context): Context { + return context.setValue(SUPPRESS_INSTRUMENTATION_KEY, false); +} + +/** + * Return current suppress instrumentation value for the given context, + * if it exists. + * + * @param context context check for the suppress instrumentation value. + */ +export function isInstrumentationSuppressed(context: Context): boolean { + return Boolean(context.getValue(SUPPRESS_INSTRUMENTATION_KEY)); +} diff --git a/src/trace/link.ts b/src/trace/link.ts index 8bd37478..1d81d38d 100644 --- a/src/trace/link.ts +++ b/src/trace/link.ts @@ -15,7 +15,7 @@ */ import { SpanAttributes } from './attributes'; -import { LinkContext } from './link_context'; +import { SpanContext } from './span_context'; /** * A pointer from the current {@link Span} to another span in the same trace or @@ -33,8 +33,8 @@ import { LinkContext } from './link_context'; * Service Provider) can be correlated. */ export interface Link { - /** The {@link LinkContext} of a linked span. */ - context: LinkContext; + /** The {@link SpanContext} of a linked span. */ + context: SpanContext; /** A set of {@link SpanAttributes} on the link. */ attributes?: SpanAttributes; } diff --git a/src/trace/link_context.ts b/src/trace/link_context.ts deleted file mode 100644 index c5224597..00000000 --- a/src/trace/link_context.ts +++ /dev/null @@ -1,22 +0,0 @@ -/* - * Copyright The 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 './span_context'; - -/** - * A pointer to another span. - */ -export type LinkContext = Pick; diff --git a/src/trace/spancontext-utils.ts b/src/trace/spancontext-utils.ts index ebcc3ce2..266471fd 100644 --- a/src/trace/spancontext-utils.ts +++ b/src/trace/spancontext-utils.ts @@ -13,6 +13,8 @@ * See the License for the specific language governing permissions and * limitations under the License. */ +import { NonRecordingSpan } from './NonRecordingSpan'; +import { Span } from './span'; import { SpanContext } from './span_context'; import { TraceFlags } from './trace_flags'; @@ -43,3 +45,13 @@ export function isSpanContextValid(spanContext: SpanContext): boolean { isValidTraceId(spanContext.traceId) && isValidSpanId(spanContext.spanId) ); } + +/** + * Wrap the given {@link SpanContext} in a new non-recording {@link Span} + * + * @param spanContext span context to be wrapped + * @returns a new non-recording {@link Span} with the provided context + */ +export function wrapSpanContext(spanContext: SpanContext): Span { + return new NonRecordingSpan(spanContext); +} diff --git a/test/noop-implementations/noop-tracer.test.ts b/test/noop-implementations/noop-tracer.test.ts index 7527ae7b..292b2fbb 100644 --- a/test/noop-implementations/noop-tracer.test.ts +++ b/test/noop-implementations/noop-tracer.test.ts @@ -21,7 +21,7 @@ import { SpanKind, TraceFlags, context, - setSpanContext, + trace, } from '../../src'; import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan'; @@ -50,7 +50,7 @@ describe('NoopTracer', () => { const span = tracer.startSpan( 'test-1', {}, - setSpanContext(context.active(), parent) + trace.setSpanContext(context.active(), parent) ); assert(span.spanContext().traceId === parent.traceId); assert(span.spanContext().spanId === parent.spanId); diff --git a/test/context/context.test.ts b/test/trace/context-utils.test.ts similarity index 95% rename from test/context/context.test.ts rename to test/trace/context-utils.test.ts index dfea20b9..1f24c34c 100644 --- a/test/context/context.test.ts +++ b/test/trace/context-utils.test.ts @@ -16,12 +16,11 @@ import * as assert from 'assert'; import { - createContextKey, isInstrumentationSuppressed, - ROOT_CONTEXT, suppressInstrumentation, unsuppressInstrumentation, -} from '../../src/context/context'; +} from '../../src/trace/context-utils'; +import { createContextKey, ROOT_CONTEXT } from '../../src/context/context'; const SUPPRESS_INSTRUMENTATION_KEY = createContextKey( 'OpenTelemetry Context Key SUPPRESS_INSTRUMENTATION' diff --git a/test/trace/spancontext-utils.test.ts b/test/trace/spancontext-utils.test.ts index e194f1d3..81dd3b1f 100644 --- a/test/trace/spancontext-utils.test.ts +++ b/test/trace/spancontext-utils.test.ts @@ -54,4 +54,17 @@ describe('spancontext-utils', () => { }; assert.ok(!context.isSpanContextValid(spanContext)); }); + + it('should wrap a SpanContext in a non-recording span', () => { + const spanContext = { + traceId: 'd4cda95b652f4a1592b449d5929fda1b', + spanId: '6e0c63257de34c92', + traceFlags: TraceFlags.NONE, + }; + + const span = context.wrapSpanContext(spanContext); + + assert.deepStrictEqual(span.spanContext(), spanContext); + assert.strictEqual(span.isRecording(), false); + }); });