Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rename scope to context #853

Merged
merged 6 commits into from
Mar 13, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions .circleci/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -44,20 +44,22 @@ cache_1: &cache_1
paths:
- ./node_modules
- ./package-lock.json
- packages/opentelemetry-base/node_modules
- packages/opentelemetry-scope-base/node_modules
- packages/opentelemetry-api/node_modules
- packages/opentelemetry-scope-async-hooks/node_modules
- packages/opentelemetry-base/node_modules
- packages/opentelemetry-context-async-hooks/node_modules
- packages/opentelemetry-context-base/node_modules
- packages/opentelemetry-context-zone/node_modules
- packages/opentelemetry-context-zone-peer-dep/node_modules
- packages/opentelemetry-core/node_modules
- packages/opentelemetry-exporter-prometheus/node_modules
- packages/opentelemetry-metrics/node_modules
- packages/opentelemetry-tracing/node_modules
- packages/opentelemetry-exporter-jaeger/node_modules
- packages/opentelemetry-exporter-prometheus/node_modules
- packages/opentelemetry-exporter-zipkin/node_modules
- packages/opentelemetry-metrics/node_modules
- packages/opentelemetry-node/node_modules
- packages/opentelemetry-plugin-dns/node_modules
- packages/opentelemetry-shim-opentracing/node_modules
- packages/opentelemetry-tracing/node_modules
- packages/opentelemetry-web/node_modules
- packages/opentelemetry-plugin-dns/node_modules

cache_2: &cache_2
key: npm-cache-02-{{ .Environment.CIRCLE_JOB }}-{{ checksum "/tmp/checksums.txt" }}-F267A71D
Expand Down
2 changes: 1 addition & 1 deletion examples/tracer-web/examples/document-load/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
Example of using Web Tracer with document load plugin with console exporter and collector exporter
<script type="text/javascript" src="document-load.js"></script>
<br/>
<button id="button1">Test WebTracer with ZoneScopeManager - async</button>
<button id="button1">Test WebTracer with ZoneContextManager - async</button>

</body>

Expand Down
6 changes: 3 additions & 3 deletions examples/tracer-web/examples/document-load/index.js
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
import { WebTracerProvider } from '@opentelemetry/web';
import { DocumentLoad } from '@opentelemetry/plugin-document-load';
import { ZoneScopeManager } from '@opentelemetry/scope-zone';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { CollectorExporter } from '@opentelemetry/exporter-collector';

const provider = new WebTracerProvider({
Expand All @@ -12,7 +12,7 @@ const provider = new WebTracerProvider({
provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));

const providerWithZone = new WebTracerProvider({
scopeManager: new ZoneScopeManager(),
contextManager: new ZoneContextManager(),
plugins: [
new DocumentLoad(),
],
Expand Down Expand Up @@ -40,7 +40,7 @@ const getData = (url) => new Promise((resolve, reject) => {
};
});

// example of keeping track of scope between async operations
// example of keeping track of context between async operations
const prepareClickEvent = () => {
const url1 = 'https://raw.githubusercontent.com/open-telemetry/opentelemetry-js/master/package.json';
const url2 = 'https://raw.githubusercontent.com/open-telemetry/opentelemetry-js/master/packages/opentelemetry-web/package.json';
Expand Down
9 changes: 6 additions & 3 deletions examples/tracer-web/examples/user-interaction/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -2,13 +2,11 @@ import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing
import { WebTracerProvider } from '@opentelemetry/web';
import { XMLHttpRequestPlugin } from '@opentelemetry/plugin-xml-http-request';
import { UserInteractionPlugin } from '@opentelemetry/plugin-user-interaction';
import { ZoneScopeManager } from '@opentelemetry/scope-zone';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { CollectorExporter } from '@opentelemetry/exporter-collector';
import { B3Propagator } from '@opentelemetry/core';

const providerWithZone = new WebTracerProvider({
HttpTextPropagator: new B3Propagator(),
scopeManager: new ZoneScopeManager(),
plugins: [
new UserInteractionPlugin(),
new XMLHttpRequestPlugin({
Expand All @@ -23,6 +21,11 @@ const providerWithZone = new WebTracerProvider({
providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new CollectorExporter()));

providerWithZone.register({
contextManager: new ZoneContextManager(),
propagator: new B3Propagator(),
});

let lastButtonId = 0;

function btnAddClick() {
Expand Down
11 changes: 7 additions & 4 deletions examples/tracer-web/examples/xml-http-request/index.js
Original file line number Diff line number Diff line change
@@ -1,13 +1,11 @@
import { ConsoleSpanExporter, SimpleSpanProcessor } from '@opentelemetry/tracing';
import { WebTracerProvider } from '@opentelemetry/web';
import { XMLHttpRequestPlugin } from '@opentelemetry/plugin-xml-http-request';
import { ZoneScopeManager } from '@opentelemetry/scope-zone';
import { ZoneContextManager } from '@opentelemetry/context-zone';
import { CollectorExporter } from '@opentelemetry/exporter-collector';
import { B3Propagator } from '@opentelemetry/core';

const providerWithZone = new WebTracerProvider({
HttpTextPropagator: new B3Propagator(),
scopeManager: new ZoneScopeManager(),
plugins: [
new XMLHttpRequestPlugin({
ignoreUrls: [/localhost:8090\/sockjs-node/],
Expand All @@ -21,6 +19,11 @@ const providerWithZone = new WebTracerProvider({
providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
providerWithZone.addSpanProcessor(new SimpleSpanProcessor(new CollectorExporter()));

providerWithZone.register({
contextManager: new ZoneContextManager(),
propagator: new B3Propagator(),
});

const webTracerWithZone = providerWithZone.getTracer('example-tracer-web');

const getData = (url) => new Promise((resolve, _reject) => {
Expand All @@ -35,7 +38,7 @@ const getData = (url) => new Promise((resolve, _reject) => {
};
});

// example of keeping track of scope between async operations
// example of keeping track of context between async operations
const prepareClickEvent = () => {
const url1 = 'https://httpbin.org/get';

Expand Down
2 changes: 1 addition & 1 deletion examples/tracer-web/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
"@opentelemetry/plugin-document-load": "^0.4.0",
"@opentelemetry/plugin-user-interaction": "^0.4.0",
"@opentelemetry/plugin-xml-http-request": "^0.4.0",
"@opentelemetry/scope-zone": "^0.4.0",
"@opentelemetry/context-zone": "^0.4.0",
"@opentelemetry/tracing": "^0.4.0",
"@opentelemetry/web": "^0.4.0"
},
Expand Down
2 changes: 1 addition & 1 deletion packages/opentelemetry-api/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@
"access": "public"
},
"dependencies": {
"@opentelemetry/scope-base": "^0.4.0"
"@opentelemetry/context-base": "^0.4.0"
},
"devDependencies": {
"@types/mocha": "^5.2.7",
Expand Down
24 changes: 13 additions & 11 deletions packages/opentelemetry-api/src/api/context.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,22 +15,22 @@
*/

import {
ScopeManager,
NoopScopeManager,
ContextManager,
NoopContextManager,
Context,
} from '@opentelemetry/scope-base';
} from '@opentelemetry/context-base';

/**
* Singleton object which represents the entry point to the OpenTelemetry Context API
*/
export class ContextAPI {
private static _instance?: ContextAPI;
private _scopeManager: ScopeManager = new NoopScopeManager();
private _contextManager: ContextManager = new NoopContextManager();

/** Empty private constructor prevents end users from constructing a new instance of the API */
private constructor() {}

/** Get the singleton instance of the Scope API */
/** Get the singleton instance of the Context API */
public static getInstance(): ContextAPI {
if (!this._instance) {
this._instance = new ContextAPI();
Expand All @@ -42,16 +42,18 @@ export class ContextAPI {
/**
* Set the current context manager. Returns the initialized context manager
*/
public setGlobalContextManager(scopeManager: ScopeManager): ScopeManager {
this._scopeManager = scopeManager;
return scopeManager;
public setGlobalContextManager(
contextManager: ContextManager
): ContextManager {
this._contextManager = contextManager;
return contextManager;
}

/**
* Get the currently active context
*/
public active(): Context {
return this._scopeManager.active();
return this._contextManager.active();
}

/**
Expand All @@ -64,7 +66,7 @@ export class ContextAPI {
context: Context,
fn: T
): ReturnType<T> {
return this._scopeManager.with(context, fn);
return this._contextManager.with(context, fn);
}

/**
Expand All @@ -74,6 +76,6 @@ export class ContextAPI {
* @param context context to bind to the event emitter or function. Defaults to the currently active context
*/
public bind<T>(target: T, context: Context = this.active()): T {
return this._scopeManager.bind(target, context);
return this._contextManager.bind(target, context);
}
}
2 changes: 1 addition & 1 deletion packages/opentelemetry-api/src/api/propagation.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
* limitations under the License.
*/

import { Context } from '@opentelemetry/scope-base';
import { Context } from '@opentelemetry/context-base';
import { defaultGetter, GetterFunction } from '../context/propagation/getter';
import { HttpTextPropagator } from '../context/propagation/HttpTextPropagator';
import { NOOP_HTTP_TEXT_PROPAGATOR } from '../context/propagation/NoopHttpTextPropagator';
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
* limitations under the License.
*/

import { Context } from '@opentelemetry/scope-base';
import { Context } from '@opentelemetry/context-base';
import { SetterFunction } from './setter';
import { GetterFunction } from './getter';

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
* limitations under the License.
*/

import { Context } from '@opentelemetry/scope-base';
import { Context } from '@opentelemetry/context-base';
import { HttpTextPropagator } from './HttpTextPropagator';

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ export interface EntryValue {
*/
export enum EntryTtl {
/**
* NO_PROPAGATION is considered to have local scope and is used within the
* NO_PROPAGATION is considered to have local context and is used within the
* process it created.
*/
NO_PROPAGATION = 0,
Expand Down
2 changes: 1 addition & 1 deletion packages/opentelemetry-api/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ export * from './trace/trace_state';
export * from './trace/tracer_provider';
export * from './trace/tracer';

export { Context } from '@opentelemetry/scope-base';
export { Context } from '@opentelemetry/context-base';

import { ContextAPI } from './api/context';
/** Entrypoint for context API */
Expand Down
6 changes: 3 additions & 3 deletions packages/opentelemetry-api/src/trace/tracer.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
* limitations under the License.
*/

import { Context } from '@opentelemetry/scope-base';
import { Context } from '@opentelemetry/context-base';
import { Span } from './span';
import { SpanOptions } from './SpanOptions';

Expand Down Expand Up @@ -58,9 +58,9 @@ export interface Tracer {
): ReturnType<T>;

/**
* Bind a span as the target's scope or propagate the current one.
* Bind a span as the target's context or propagate the current one.
*
* @param target Any object to which a scope need to be set
* @param target Any object to which a context need to be set
* @param [context] Optionally specify the context which you want to bind
*/
bind<T>(target: T, context?: Span): T;
Expand Down
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
# OpenTelemetry AsyncHooks-based Scope Manager
# OpenTelemetry AsyncHooks-based Context Manager
[![Gitter chat][gitter-image]][gitter-url]
[![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 [async-hooks][async-hooks-doc] based scope manager which is used internally by OpenTelemetry plugins to propagate specific scope between function calls and async operations. It only targets NodeJS since async-hooks is only available there.
This package provides [async-hooks][async-hooks-doc] based context manager which is used internally by OpenTelemetry plugins to propagate specific context between function calls and async operations. It only targets NodeJS since async-hooks is only available there.

## What is a ScopeManager ?
## What is a ContextManager ?

The definition and why they exist is available on [the readme of the scope-base package][def-scope-manager].
The definition and why they exist is available on [the readme of the context-base package][def-context-manager].

### Implementation in NodeJS

NodeJS has a specific API to track async scope: [async-hooks][async-hooks-doc], it allows to track creation of new async operation and their respective parent.
NodeJS has a specific API to track async context: [async-hooks][async-hooks-doc], it allows to track creation of new async operation and their respective parent.
This package only handle storing a specific object for a given async hooks context.

### Limitations

Even if the API is native to NodeJS, it doesn't cover all possible cases of scope propagation but there is a big effort from the NodeJS team to fix those. That's why we generally advise to be on the latest LTS to benefit from performance and bug fixes.
Even if the API is native to NodeJS, it doesn't cover all possible cases of context propagation but there is a big effort from the NodeJS team to fix those. That's why we generally advise to be on the latest LTS to benefit from performance and bug fixes.

There are known modules that break scope propagation ([some of them are listed there][pkgs-that-break-ah]), so it's possible that the scope manager doesn't work with them.
There are known modules that break context propagation ([some of them are listed there][pkgs-that-break-ah]), so it's possible that the context manager doesn't work with them.

### Prior arts

Expand All @@ -44,15 +44,15 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
[gitter-url]: https://gitter.im/open-telemetry/opentelemetry-node?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
[license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/master/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/status.svg?path=packages/opentelemetry-scope-async-hooks
[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-scope-async-hooks
[devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/dev-status.svg?path=packages/opentelemetry-scope-async-hooks
[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-scope-async-hooks&type=dev
[dependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/status.svg?path=packages/opentelemetry-context-async-hooks
[dependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-context-async-hooks
[devDependencies-image]: https://david-dm.org/open-telemetry/opentelemetry-js/dev-status.svg?path=packages/opentelemetry-context-async-hooks
[devDependencies-url]: https://david-dm.org/open-telemetry/opentelemetry-js?path=packages%2Fopentelemetry-context-async-hooks&type=dev
[async-hooks-doc]: http://nodejs.org/dist/latest/docs/api/async_hooks.html
[def-scope-manager]: https://github.com/open-telemetry/opentelemetry-js/blob/master/packages/opentelemetry-scope-base/README.md
[def-context-manager]: https://github.com/open-telemetry/opentelemetry-js/blob/master/packages/opentelemetry-context-base/README.md
[dd-js-tracer-scope]: https://github.com/DataDog/dd-trace-js/tree/master/packages/dd-trace/src/scope
[opentracing-scope]: https://github.com/opentracing/opentracing-javascript/pull/113
[diag-team-scope-discussion]: https://github.com/nodejs/diagnostics/issues/300
[pkgs-that-break-ah]: https://github.com/nodejs/diagnostics/blob/master/tracing/AsyncHooks/problematic-modules.md
[npm-url]: https://www.npmjs.com/package/@opentelemetry/scope-async-hooks
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fscope-async-hooks.svg
[npm-url]: https://www.npmjs.com/package/@opentelemetry/context-async-hooks
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fcontext-async-hooks.svg
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"name": "@opentelemetry/scope-async-hooks",
"name": "@opentelemetry/context-async-hooks",
"version": "0.4.0",
"description": "OpenTelemetry AsyncHooks-based Scope Manager",
"description": "OpenTelemetry AsyncHooks-based Context Manager",
"main": "build/src/index.js",
"types": "build/src/index.d.ts",
"repository": "open-telemetry/opentelemetry-js",
Expand Down Expand Up @@ -56,6 +56,6 @@
"typescript": "3.7.2"
},
"dependencies": {
"@opentelemetry/scope-base": "^0.4.0"
"@opentelemetry/context-base": "^0.4.0"
}
}
Loading