diff --git a/README.md b/README.md index 96bbc542..074a0ec2 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,39 @@ + +--- +

+ + API Documentation +   •   + Getting In Touch (GitHub Discussions) + +

+ +

+ + GitHub release (latest by date including pre-releases) + + + Codecov Status + + + license + +
+ + Build Status + + + Build Status + +

+ +--- + # OpenTelemetry API for JavaScript [![NPM Published Version][npm-img]][npm-url] [![dependencies][dependencies-image]][dependencies-url] [![devDependencies][devDependencies-image]][devDependencies-url] -[![Apache License][license-image]][license-image] This package provides everything needed to interact with the OpenTelemetry API, including all TypeScript interfaces, enums, and no-op implementations. It is intended for use both on the server and in the browser. @@ -50,7 +80,7 @@ const tracer = trace.getTracer(name, version); // Trace your application by creating spans async function operation() { const span = tracer.startSpan("do operation"); - + // mock some work by sleeping 1 second await new Promise((resolve, reject) => { setTimeout(resolve, 1000); @@ -73,6 +103,13 @@ main(); Because the npm installer and node module resolution algorithm could potentially allow two or more copies of any given package to exist within the same `node_modules` structure, the OpenTelemetry API takes advantage of a variable on the `global` object to store the global API. When an API method in the API package is called, it checks if this `global` API exists and proxies calls to it if and only if it is a compatible API version. This means if a package has a dependency on an OpenTelemetry API version which is not compatible with the API used by the end user, the package will receive a no-op implementation of the API. +## Upgrade Guidelines + +### 1.0.0-rc.0 to x + +- `HttpBaggage` renamed to `HttpBaggagePropagator` +- [#45](https://github.com/open-telemetry/opentelemetry-js-api/pull/45) `Span#context` renamed to `Span#spanContext` + ## Useful links - For more information on OpenTelemetry, visit: @@ -88,12 +125,11 @@ Apache 2.0 - See [LICENSE][license-url] for more information. [discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions [license-url]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/LICENSE [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat -[dependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js-api/status.svg +[dependencies-image]: https://status.david-dm.org/gh/open-telemetry/opentelemetry-js-api.svg [dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-api -[devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js-api/dev-status.svg +[devDependencies-image]: https://status.david-dm.org/gh/open-telemetry/opentelemetry-js-api.svg?type=dev [devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js-api?type=dev [npm-url]: https://www.npmjs.com/package/@opentelemetry/api [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fapi.svg - [docs-tracing]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/tracing.md [docs-sdk-registration]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/sdk-registration.md diff --git a/src/context/context.ts b/src/context/context.ts index 6e59831b..0be6163e 100644 --- a/src/context/context.ts +++ b/src/context/context.ts @@ -16,7 +16,7 @@ import { Context } from './types'; import { Baggage, Span, SpanContext } from '../'; -import { NoopSpan } from '../trace/NoopSpan'; +import { NonRecordingSpan } from '../trace/NonRecordingSpan'; /** * span key @@ -56,7 +56,7 @@ export function setSpan(context: Context, span: Span): Context { } /** - * Wrap span context in a NoopSpan and set as span in a new + * Wrap span context in a NonRecordingSpan and set as span in a new * context * * @param context context to set active span on @@ -66,7 +66,7 @@ export function setSpanContext( context: Context, spanContext: SpanContext ): Context { - return setSpan(context, new NoopSpan(spanContext)); + return setSpan(context, new NonRecordingSpan(spanContext)); } /** @@ -75,7 +75,7 @@ export function setSpanContext( * @param context context to get values from */ export function getSpanContext(context: Context): SpanContext | undefined { - return getSpan(context)?.context(); + return getSpan(context)?.spanContext(); } /** diff --git a/src/trace/NoopSpan.ts b/src/trace/NonRecordingSpan.ts similarity index 89% rename from src/trace/NoopSpan.ts rename to src/trace/NonRecordingSpan.ts index 40f238d3..bd5e321e 100644 --- a/src/trace/NoopSpan.ts +++ b/src/trace/NonRecordingSpan.ts @@ -23,17 +23,17 @@ import { SpanStatus } from './status'; import { INVALID_SPAN_CONTEXT } from './spancontext-utils'; /** - * The NoopSpan is the default {@link Span} that is used when no Span + * The NonRecordingSpan is the default {@link Span} that is used when no Span * implementation is available. All operations are no-op including context * propagation. */ -export class NoopSpan implements Span { +export class NonRecordingSpan implements Span { constructor( private readonly _spanContext: SpanContext = INVALID_SPAN_CONTEXT ) {} // Returns a SpanContext. - context(): SpanContext { + spanContext(): SpanContext { return this._spanContext; } @@ -65,7 +65,7 @@ export class NoopSpan implements Span { // By default does nothing end(_endTime?: TimeInput): void {} - // isRecording always returns false for noopSpan. + // isRecording always returns false for NonRecordingSpan. isRecording(): boolean { return false; } diff --git a/src/trace/NoopTracer.ts b/src/trace/NoopTracer.ts index b24ee3c6..14e58421 100644 --- a/src/trace/NoopTracer.ts +++ b/src/trace/NoopTracer.ts @@ -16,7 +16,7 @@ import { getSpanContext } from '../context/context'; import { Context } from '../context/types'; -import { NoopSpan } from './NoopSpan'; +import { NonRecordingSpan } from './NonRecordingSpan'; import { Span } from './span'; import { isSpanContextValid } from './spancontext-utils'; import { SpanOptions } from './SpanOptions'; @@ -31,7 +31,7 @@ export class NoopTracer implements Tracer { startSpan(name: string, options?: SpanOptions, context?: Context): Span { const root = Boolean(options?.root); if (root) { - return new NoopSpan(); + return new NonRecordingSpan(); } const parentFromContext = context && getSpanContext(context); @@ -40,9 +40,9 @@ export class NoopTracer implements Tracer { isSpanContext(parentFromContext) && isSpanContextValid(parentFromContext) ) { - return new NoopSpan(parentFromContext); + return new NonRecordingSpan(parentFromContext); } else { - return new NoopSpan(); + return new NonRecordingSpan(); } } } diff --git a/src/trace/span.ts b/src/trace/span.ts index 7d8b94b5..d80b8c26 100644 --- a/src/trace/span.ts +++ b/src/trace/span.ts @@ -39,7 +39,7 @@ export interface Span { * * @returns the SpanContext object associated with this Span. */ - context(): SpanContext; + spanContext(): SpanContext; /** * Sets an attribute to the span. diff --git a/test/api/api.test.ts b/test/api/api.test.ts index 4fcad808..8049f25f 100644 --- a/test/api/api.test.ts +++ b/test/api/api.test.ts @@ -34,7 +34,7 @@ import api, { diag, } from '../../src'; import { DiagAPI } from '../../src/api/diag'; -import { NoopSpan } from '../../src/trace/NoopSpan'; +import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan'; // DiagLogger implementation const diagLoggerFunctions = [ @@ -78,7 +78,7 @@ describe('API', () => { spanId: '6e0c63257de34c92', traceFlags: TraceFlags.NONE, }; - const dummySpan = new NoopSpan(spanContext); + const dummySpan = new NonRecordingSpan(spanContext); beforeEach(() => { context.disable(); diff --git a/test/noop-implementations/noop-span.test.ts b/test/noop-implementations/noop-span.test.ts index d2974fca..de0007ae 100644 --- a/test/noop-implementations/noop-span.test.ts +++ b/test/noop-implementations/noop-span.test.ts @@ -21,11 +21,11 @@ import { INVALID_TRACEID, TraceFlags, } from '../../src'; -import { NoopSpan } from '../../src/trace/NoopSpan'; +import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan'; -describe('NoopSpan', () => { +describe('NonRecordingSpan', () => { it('do not crash', () => { - const span = new NoopSpan(); + const span = new NonRecordingSpan(); span.setAttribute('my_string_attribute', 'foo'); span.setAttribute('my_number_attribute', 123); span.setAttribute('my_boolean_attribute', false); @@ -44,7 +44,7 @@ describe('NoopSpan', () => { span.updateName('my-span'); assert.ok(!span.isRecording()); - assert.deepStrictEqual(span.context(), { + assert.deepStrictEqual(span.spanContext(), { traceId: INVALID_TRACEID, spanId: INVALID_SPANID, traceFlags: TraceFlags.NONE, diff --git a/test/noop-implementations/noop-tracer.test.ts b/test/noop-implementations/noop-tracer.test.ts index 661ff34d..7527ae7b 100644 --- a/test/noop-implementations/noop-tracer.test.ts +++ b/test/noop-implementations/noop-tracer.test.ts @@ -23,20 +23,20 @@ import { context, setSpanContext, } from '../../src'; -import { NoopSpan } from '../../src/trace/NoopSpan'; +import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan'; describe('NoopTracer', () => { it('should not crash', () => { const tracer = new NoopTracer(); - assert.ok(tracer.startSpan('span-name') instanceof NoopSpan); + assert.ok(tracer.startSpan('span-name') instanceof NonRecordingSpan); assert.ok( tracer.startSpan('span-name1', { kind: SpanKind.CLIENT }) instanceof - NoopSpan + NonRecordingSpan ); assert.ok( tracer.startSpan('span-name2', { kind: SpanKind.CLIENT }) instanceof - NoopSpan + NonRecordingSpan ); }); @@ -52,8 +52,8 @@ describe('NoopTracer', () => { {}, setSpanContext(context.active(), parent) ); - assert(span.context().traceId === parent.traceId); - assert(span.context().spanId === parent.spanId); - assert(span.context().traceFlags === parent.traceFlags); + assert(span.spanContext().traceId === parent.traceId); + assert(span.spanContext().spanId === parent.spanId); + assert(span.spanContext().traceFlags === parent.traceFlags); }); }); diff --git a/test/proxy-implementations/proxy-tracer.test.ts b/test/proxy-implementations/proxy-tracer.test.ts index c6e2756c..c350913a 100644 --- a/test/proxy-implementations/proxy-tracer.test.ts +++ b/test/proxy-implementations/proxy-tracer.test.ts @@ -27,7 +27,7 @@ import { ROOT_CONTEXT, SpanOptions, } from '../../src'; -import { NoopSpan } from '../../src/trace/NoopSpan'; +import { NonRecordingSpan } from '../../src/trace/NonRecordingSpan'; describe('ProxyTracer', () => { let provider: ProxyTracerProvider; @@ -51,14 +51,14 @@ describe('ProxyTracer', () => { it('startSpan should return Noop Spans', () => { const tracer = provider.getTracer('test'); - assert.ok(tracer.startSpan('span-name') instanceof NoopSpan); + assert.ok(tracer.startSpan('span-name') instanceof NonRecordingSpan); assert.ok( tracer.startSpan('span-name1', { kind: SpanKind.CLIENT }) instanceof - NoopSpan + NonRecordingSpan ); assert.ok( tracer.startSpan('span-name2', { kind: SpanKind.CLIENT }) instanceof - NoopSpan + NonRecordingSpan ); }); }); @@ -91,7 +91,7 @@ describe('ProxyTracer', () => { let delegateTracer: Tracer; beforeEach(() => { - delegateSpan = new NoopSpan(); + delegateSpan = new NonRecordingSpan(); delegateTracer = { startSpan() { return delegateSpan;