# @opentelemetry/context-async-hooks > OpenTelemetry AsyncLocalStorage-based Context Manager Latest version **2.11.0** (published 2026-08-31) · Apache-2.0 license · 0 weekly downloads ## Install ```sh npm install @opentelemetry/context-async-hooks pnpm add @opentelemetry/context-async-hooks yarn add @opentelemetry/context-async-hooks bun add @opentelemetry/context-async-hooks ``` ## Health **Score 70/100 (B)** — status: active. Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score. Warnings: low downloads; no esm support. ## Facts | | | |---|---| | Version | 2.11.0 | | Published | 2026-08-31 | | First published | 2020-03-16 | | Weekly downloads | 0 | | License | Apache-2.0 | | TypeScript types | bundled | | Module format | CommonJS | | Node | ^18.19.0 \|\| >=20.6.0 | | Dependencies | 0 | | Unpacked size | 61.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Provenance | attested (GitHub Actions) | | GitHub stars | 3476 | | Author | OpenTelemetry Authors | | Maintainers | dyladan, pichlermarc, overbalance, npmjs-account, trentm, martinkuba | | Keywords | opentelemetry, nodejs, tracing, profiling, metrics, stats | ## Links - npm: https://www.npmjs.com/package/@opentelemetry/context-async-hooks - Repository: https://github.com/open-telemetry/opentelemetry-js - Homepage: https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-context-async-hooks - Issues: https://github.com/open-telemetry/opentelemetry-js/issues - npm.io page: https://npm.io/package/@opentelemetry/context-async-hooks ## Recent versions - 2.11.0 (latest) — 2026-08-31 - 3.0.0-development.0 (canary) — 2026-09-21 - 1.8.0 (next) — 2022-11-09 - 2.11.0-development.0 — 2026-08-31 - 2.10.0 — 2026-07-21 - 2.9.0 — 2026-07-02 - 2.8.0 — 2026-06-11 - 2.7.1 — 2026-04-29 - 2.7.0 — 2026-04-17 - 2.6.1 — 2026-03-25 - 2.6.0 — 2026-03-03 - 2.5.1 — 2026-02-12 - 2.5.0 — 2026-01-21 - 2.4.0 — 2026-01-14 - 2.3.0 — 2026-01-08 - … 129 more at https://npm.io/package/@opentelemetry/context-async-hooks/versions ## README # OpenTelemetry async_hooks-based Context Managers [![NPM Published Version][npm-img]][npm-url] [![Apache License][license-image]][license-image] This package provides two [`ContextManager`](https://open-telemetry.github.io/opentelemetry-js/interfaces/_opentelemetry_api.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). See [the definition of the `ContextManager` interface][def-context-manager] and the problem it solves. ## 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). This is **deprecated** and will be removed in v3 (planned for mid-2025). `AsyncLocalStorage` is simpler, faster, available in Node.js v14.8.0 and later, and avoids [this possible DoS vulnerability](https://nodejs.org/en/blog/vulnerability/january-2026-dos-mitigation-async-hooks). ### Using attach() `AsyncLocalStorageContextManager` supports the optional `attach()` method for imperative context management. It sets a context as active and returns a disposable `Token`. Disposing the token restores the previously active context. **What is an "execution unit"?** In Node.js, this refers to the current asynchronous execution chain - the currently running code plus all async operations that will be spawned from it (Promises, callbacks, async/await, timers, etc.). When you `attach()` a context, it becomes active for this entire chain until the token is disposed. ```javascript import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks'; import { ROOT_CONTEXT } from '@opentelemetry/api'; const contextManager = new AsyncLocalStorageContextManager(); contextManager.enable(); const myContext = ROOT_CONTEXT.setValue('key', 'value'); // Attach a context - it becomes active for the current async execution chain const token = contextManager.attach(myContext); console.log(contextManager.active()); // myContext // Context propagates to async operations automatically await someAsyncOperation(); console.log(contextManager.active()); // still myContext // Restore the previous context by disposing the token token.dispose(); console.log(contextManager.active()); // ROOT_CONTEXT ``` **Important:** You should ensure that every `attach()` call has a corresponding `token.dispose()` call to avoid context leaks. Use a try/finally block for safety: ```javascript const token = contextManager.attach(myContext); try { await doWork(); } finally { token.dispose(); // Always restore } ``` For most use cases, prefer using `with()` as it automatically handles context restoration. Not restoring context properly can lead to catastrophic effects on your telemetry, even outside the bounds of your instrumentation library. ## 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][dd-js-tracer-scope] for their JavaScript tracer - [OpenTracing implementation][opentracing-scope] - [Discussion about context propagation][diag-team-scope-discussion] by the Node.js Diagnostics Working Group ## 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] ## License 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/blob/main/LICENSE [license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat [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 [npm-url]: https://www.npmjs.com/package/@opentelemetry/context-async-hooks [npm-img]: https://badge.fury.io/js/%40opentelemetry%2Fcontext-async-hooks.svg --- _Source: https://npm.io/package/@opentelemetry/context-async-hooks · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._