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.

Sign up for GitHub

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

Jump to bottom

docs(context): Fix links, edit prose #2619

Merged
merged 11 commits into from
Jan 31, 2022
Merged

docs(context): Fix links, edit prose #2619

Changes from 6 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
e86bb17
fix pkgs-that-break-ah link
spencerwilson Jun 13, 2021
7d9c732
doc(context): Fix links, edit prose
spencerwilson Nov 12, 2021
2993bf8
Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…
spencerwilson Nov 12, 2021
1ed9290
restore newline
spencerwilson Nov 12, 2021
4f820cb
Merge branch 'main' into sw/context-docs
dyladan Jan 6, 2022
85a4319
Update packages/opentelemetry-context-async-hooks/README.md
dyladan Jan 6, 2022
34ece4b
Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…
spencerwilson Jan 22, 2022
ca416e3
docs(context-async-hooks): copy changes
spencerwilson Jan 24, 2022
6e5ab03
docs(lint): maybe fix things
spencerwilson Jan 24, 2022
8162621
Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…
spencerwilson Jan 27, 2022
5e9368a
Merge branch 'main' into sw/context-docs
vmarchaud Jan 31, 2022
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
39 changes: 24 additions & 15 deletions packages/opentelemetry-context-async-hooks/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,33 +1,42 @@
# OpenTelemetry AsyncHooks-based Context Manager
# OpenTelemetry async_hooks-based Context Managers

[![NPM Published Version][npm-img]][npm-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.

## What is a ContextManager
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].

### Implementation in NodeJS

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.
## API

Two `ContextManager` implementations are exported:

* `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)

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),
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AsyncLocalStorage isn't available for Node < 14.6 so we should document this there

Copy link
Member

@blumamir blumamir Jan 6, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is also available for node ^12.17 and node ^13.10

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

According to the node 14 docs it was introduced in 13.10 so I think it is available in all v14 versions.

Copy link
Member

@Flarna Flarna Jan 7, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please note that AsyncLocalStorage was added as experimental in 13.10 and it is still marked as experimental on 12 and 14 release lines (ignoring 13 and 15 for now as they are EOL anyway).

It was move out of experimental with 16.4.0.

There were several important fixes done in that area during the first 14.x releases resulting in using it only for >=14.8.0 in NodeTracerProvider.

I think all these fixes were backported to the 12.x line but most likely not with 12.17.0.


> 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.
dyladan marked this conversation as resolved.
Show resolved Hide resolved

`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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is the only relevant fix, it's the latest one.


### Limitations
## Limitations

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.
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.

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.
vmarchaud marked this conversation as resolved.
Show resolved Hide resolved
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 arts
## Prior art

Context propagation is a big subject when talking about tracing in NodeJS, if you want more information about that here are some resources:
Context propagation is a big subject when talking about tracing in Node.js. If you want more information about it here are some resources:

- <https://www.npmjs.com/package/continuation-local-storage> (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

Expand All @@ -43,7 +52,7 @@ Apache 2.0 - See [LICENSE][license-url] for more information.
[license-url]: https://github.com/open-telemetry/opentelemetry-js/blob/main/LICENSE
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[async-hooks-doc]: http://nodejs.org/dist/latest/docs/api/async_hooks.html
[def-context-manager]: https://github.com/open-telemetry/opentelemetry-js-api/blob/main/docs/context.md#context-manager
[def-context-manager]: https://opentelemetry.io/docs/instrumentation/js/api/context/#context-manager
[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
Expand Down