OpenTelemetry SDK
    Preparing search index...

    Module @opentelemetry/context-async-hooks

    OpenTelemetry async_hooks-based Context Managers

    NPM Published Version Apache License

    This package provides a ContextManager implementation 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 or opentelemetry-context-zone-peer-dep.

    See the definition of the ContextManager interface and the problem it solves.

    A ContextManager implementations is exported:

    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.

    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:

    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.

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

    Apache 2.0 - See LICENSE for more information.

    Settings
    Member Visibility

    On This Page
    OpenTelemetry async_hooks-based Context Managers