From e86bb17de234ba35be50cfb5069efb698aec2d30 Mon Sep 17 00:00:00 2001 From: Spencer Wilson <5624115+spencerwilson@users.noreply.github.com> Date: Sun, 13 Jun 2021 15:44:24 -0700 Subject: [PATCH 1/6] fix pkgs-that-break-ah link --- packages/opentelemetry-context-async-hooks/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/opentelemetry-context-async-hooks/README.md b/packages/opentelemetry-context-async-hooks/README.md index dfdff04b56..cc35cac253 100644 --- a/packages/opentelemetry-context-async-hooks/README.md +++ b/packages/opentelemetry-context-async-hooks/README.md @@ -20,7 +20,7 @@ This package only handle storing a specific object for a given async hooks conte 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 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. +async-hooks may not work perfectly with some packages; see [here][pkgs-that-break-ah] for known issues. Consequently, it's possible that opentelemetry-context-async-hooks won't work reliably if context runs through those packages. ### Prior arts @@ -53,6 +53,6 @@ Apache 2.0 - See [LICENSE][license-url] for more information. [dd-js-tracer-scope]: https://github.com/DataDog/dd-trace-js/tree/main/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 +[pkgs-that-break-ah]: https://github.com/nodejs/diagnostics/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aasync-continuity [npm-url]: https://www.npmjs.com/package/@opentelemetry/context-async-hooks [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fcontext-async-hooks.svg From 7d9c7320dbb2dd0ecad8ae8d49f2a43b12f1057d Mon Sep 17 00:00:00 2001 From: Spencer Wilson <5624115+spencerwilson@users.noreply.github.com> Date: Thu, 11 Nov 2021 17:15:19 -0800 Subject: [PATCH 2/6] doc(context): Fix links, edit prose --- .../README.md | 36 ++++++++++--------- 1 file changed, 20 insertions(+), 16 deletions(-) diff --git a/packages/opentelemetry-context-async-hooks/README.md b/packages/opentelemetry-context-async-hooks/README.md index cc35cac253..2f606b6d17 100644 --- a/packages/opentelemetry-context-async-hooks/README.md +++ b/packages/opentelemetry-context-async-hooks/README.md @@ -1,35 +1,39 @@ -# OpenTelemetry AsyncHooks-based Context Manager +# OpenTelemetry async_hooks-based Context Managers [![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 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. +This package provides two [`ContextManager`](https://open-telemetry.github.io/opentelemetry-js-api/interfaces/contextmanager.html) implementations built on APIs from Node.js's [`async_hooks`][async-hooks-doc] module. If you're looking for a `ContextManager` to use in browser environments, consider [opentelemetry-context-zone](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-zone) or [opentelemetry-context-zone-peer-dep](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-zone-peer-dep). -## What is a ContextManager +An introduction to the `ContextManager` interface and the problem it solves can be found [here](https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/context.md). -The definition and why they exist is available on [the readme of the context-base package][def-context-manager]. +## API -### Implementation in NodeJS +Two `ContextManager` implementations are exported: -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. +* `AsyncLocalStorageContextManager`, based on [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) +* `AsyncHooksContextManager`, based on [`AsyncHook`](https://nodejs.org/api/async_hooks.html#async_hooks_class_asynchook) -### Limitations +The former should be preferred over the latter as its implementation is substantially simpler than the latter's, and according to [Node.js docs](https://github.com/nodejs/node/blame/v17.1.0/doc/api/async_context.md#L42-L45), -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. +> While you can create your own implementation [of `AsyncLocalStorage`] on top of [`AsyncHook`], `AsyncLocalStorage` should be preferred as it is a performant and memory safe implementation that involves significant optimizations that are non-obvious to implement. -async-hooks may not work perfectly with some packages; see [here][pkgs-that-break-ah] for known issues. Consequently, it's possible that opentelemetry-context-async-hooks won't work reliably if context runs through those packages. +## Limitations -### Prior arts +It's possible that this package won't track context perfectly when used with certain packages. In particular, it inherits any bugs present in async_hooks. See [here][pkgs-that-break-ah] for known issues. -Context propagation is a big subject when talking about tracing in NodeJS, if you want more information about that here are some resources: +async_hooks is still seeing significant correctness and performance fixes, it's recommended to run the latest Node.js LTS release to benefit from said fixes. + +## Prior art + +Context propagation is a big subject when talking about tracing in Node.js. If you want more information about it here are some resources: - (which was the old way of doing context propagation) -- Datadog's own implementation for their Javascript tracer: [here][dd-js-tracer-scope] +- Datadog's own implementation for their JavaScript tracer: [here][dd-js-tracer-scope] - OpenTracing implementation: [here][opentracing-scope] -- Discussion about context propagation by the NodeJS diagnostics working group: [here][diag-team-scope-discussion] +- Discussion about context propagation by the Node.js Diagnostics Working Group: [here][diag-team-scope-discussion] ## Useful links @@ -50,9 +54,9 @@ Apache 2.0 - See [LICENSE][license-url] for more information. [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-context-manager]: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-context-base/README.md -[dd-js-tracer-scope]: https://github.com/DataDog/dd-trace-js/tree/main/packages/dd-trace/src/scope +[dd-js-tracer-scope]: https://github.com/DataDog/dd-trace-js/blob/master/packages/dd-trace/src/scope.js [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/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aasync-continuity [npm-url]: https://www.npmjs.com/package/@opentelemetry/context-async-hooks -[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fcontext-async-hooks.svg +[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fcontext-async-hooks.svg \ No newline at end of file From 1ed92902855c3352d3e868c8f64698148d413470 Mon Sep 17 00:00:00 2001 From: Spencer Wilson <5624115+spencerwilson@users.noreply.github.com> Date: Thu, 11 Nov 2021 17:58:37 -0800 Subject: [PATCH 3/6] restore newline --- packages/opentelemetry-context-async-hooks/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/opentelemetry-context-async-hooks/README.md b/packages/opentelemetry-context-async-hooks/README.md index 2f606b6d17..63ac6a8772 100644 --- a/packages/opentelemetry-context-async-hooks/README.md +++ b/packages/opentelemetry-context-async-hooks/README.md @@ -59,4 +59,4 @@ Apache 2.0 - See [LICENSE][license-url] for more information. [diag-team-scope-discussion]: https://github.com/nodejs/diagnostics/issues/300 [pkgs-that-break-ah]: https://github.com/nodejs/diagnostics/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Aasync-continuity [npm-url]: https://www.npmjs.com/package/@opentelemetry/context-async-hooks -[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fcontext-async-hooks.svg \ No newline at end of file +[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fcontext-async-hooks.svg From 85a4319c99df18a186f21cb64b4f00a453289eb4 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Thu, 6 Jan 2022 11:14:46 -0500 Subject: [PATCH 4/6] Update packages/opentelemetry-context-async-hooks/README.md --- packages/opentelemetry-context-async-hooks/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/opentelemetry-context-async-hooks/README.md b/packages/opentelemetry-context-async-hooks/README.md index 8160cbbd62..8f04fc580a 100644 --- a/packages/opentelemetry-context-async-hooks/README.md +++ b/packages/opentelemetry-context-async-hooks/README.md @@ -20,6 +20,9 @@ The former should be preferred over the latter as its implementation is substant > While you can create your own implementation [of `AsyncLocalStorage`] on top of [`AsyncHook`], `AsyncLocalStorage` should be preferred as it is a performant and memory safe implementation that involves significant optimizations that are non-obvious to implement. +`AsyncLocalStorage` is available in node `^12.17.0 || >= 13.10.0`, however `AsyncLocalStorageContextManager` is not enabled by default for node `<14.8.0` because of some important bugfixes which were introduced in `v14.8.0`. +For more information see [nodejs/node#34573](https://github.com/nodejs/node/pull/34573). + ## Limitations It's possible that this package won't track context perfectly when used with certain packages. In particular, it inherits any bugs present in async_hooks. See [here][pkgs-that-break-ah] for known issues. From ca416e3179cc8c57492d5e59f614fbe79df9115d Mon Sep 17 00:00:00 2001 From: Spencer Wilson <5624115+spencerwilson@users.noreply.github.com> Date: Sun, 23 Jan 2022 22:10:00 -0800 Subject: [PATCH 5/6] docs(context-async-hooks): copy changes --- packages/opentelemetry-context-async-hooks/README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/packages/opentelemetry-context-async-hooks/README.md b/packages/opentelemetry-context-async-hooks/README.md index 8f04fc580a..c8e0be1295 100644 --- a/packages/opentelemetry-context-async-hooks/README.md +++ b/packages/opentelemetry-context-async-hooks/README.md @@ -5,9 +5,7 @@ This package provides two [`ContextManager`](https://open-telemetry.github.io/opentelemetry-js-api/interfaces/contextmanager.html) implementations built on APIs from Node.js's [`async_hooks`][async-hooks-doc] module. If you're looking for a `ContextManager` to use in browser environments, consider [opentelemetry-context-zone](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-zone) or [opentelemetry-context-zone-peer-dep](https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-zone-peer-dep). -An introduction to the `ContextManager` interface and the problem it solves can be found [here](https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/context.md). -The definition and why they exist is available on [the document for context manager][def-context-manager]. - +The definition of the `ContextManager` interface and the problem it solves can be found [here](def-context-manager). ## API @@ -20,8 +18,7 @@ The former should be preferred over the latter as its implementation is substant > While you can create your own implementation [of `AsyncLocalStorage`] on top of [`AsyncHook`], `AsyncLocalStorage` should be preferred as it is a performant and memory safe implementation that involves significant optimizations that are non-obvious to implement. -`AsyncLocalStorage` is available in node `^12.17.0 || >= 13.10.0`, however `AsyncLocalStorageContextManager` is not enabled by default for node `<14.8.0` because of some important bugfixes which were introduced in `v14.8.0`. -For more information see [nodejs/node#34573](https://github.com/nodejs/node/pull/34573). +`AsyncLocalStorage` is available in node `^12.17.0 || >= 13.10.0`, however `AsyncLocalStorageContextManager` is not enabled by default for node `<14.8.0` because of some important bugfixes which were introduced in `v14.8.0` (e.g., [nodejs/node#34573](https://github.com/nodejs/node/pull/34573)). ## Limitations From 6e5ab03a6f14d6eb0c71488d8f3326902f659087 Mon Sep 17 00:00:00 2001 From: Spencer Wilson <5624115+spencerwilson@users.noreply.github.com> Date: Sun, 23 Jan 2022 22:11:54 -0800 Subject: [PATCH 6/6] docs(lint): maybe fix things --- .../opentelemetry-context-async-hooks/README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/opentelemetry-context-async-hooks/README.md b/packages/opentelemetry-context-async-hooks/README.md index c8e0be1295..553156d7c7 100644 --- a/packages/opentelemetry-context-async-hooks/README.md +++ b/packages/opentelemetry-context-async-hooks/README.md @@ -30,16 +30,16 @@ async_hooks is still seeing significant correctness and performance fixes, it's Context propagation is a big subject when talking about tracing in Node.js. If you want more information about it here are some resources: -- (which was the old way of doing context propagation) -- Datadog's own implementation for their JavaScript tracer: [here][dd-js-tracer-scope] -- OpenTracing implementation: [here][opentracing-scope] -- Discussion about context propagation by the Node.js Diagnostics Working Group: [here][diag-team-scope-discussion] +* (which was the old way of doing context propagation) +* Datadog's own implementation for their JavaScript tracer: [here][dd-js-tracer-scope] +* OpenTracing implementation: [here][opentracing-scope] +* Discussion about context propagation by the Node.js Diagnostics Working Group: [here][diag-team-scope-discussion] ## Useful links -- For more information on OpenTelemetry, visit: -- For more about OpenTelemetry JavaScript: -- For help or feedback on this project, join us in [GitHub Discussions][discussions-url] +* For more information on OpenTelemetry, visit: +* For more about OpenTelemetry JavaScript: +* For help or feedback on this project, join us in [GitHub Discussions][discussions-url] ## License