merge from main

Author: trentm

.github/workflows/docs-test.yml

@@ -0,0 +1,36 @@
+name: Documentation tests
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          cache: 'npm'
+          cache-dependency-path: |
+            package-lock.json
+          node-version: ^26.3.0
+
+      - name: Bootstrap
+        run: npm ci --ignore-scripts
+
+      - name: Build documentation
+        run: |
+          npm run compile
+          NODE_OPTIONS=--max-old-space-size=6144 npm run docs
+
+      - name: Check documentation links
+        run: npm run docs:test

.github/workflows/lint.yml

@@ -33,9 +33,3 @@ jobs:
         run: |
           npm run lint
           npm run lint:examples
-
-      - name: Lint doc files
-        run: |
-          npm run compile
-          NODE_OPTIONS=--max-old-space-size=6144 npm run docs
-          npm run docs:test

.github/workflows/ossf-scorecard.yml

@@ -8,40 +8,12 @@ on:
     - cron: "44 18 * * 6" # once a week
   workflow_dispatch:
 
-permissions: read-all
+permissions: {}
 
 jobs:
   analysis:
-    runs-on: ubuntu-latest
     permissions:
-      # Needed for Code scanning upload
-      security-events: write
-      # Needed for GitHub OIDC token if publish_results is true
-      id-token: write
-    steps:
-      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
-        with:
-          persist-credentials: false
-
-      - uses: ossf/scorecard-action@2d1146689b8cda280b9bc96326124645441f03bc # v2.4.4
-        with:
-          results_file: results.sarif
-          results_format: sarif
-          publish_results: true
-
-      # Upload the results as artifacts (optional). Commenting out will disable
-      # uploads of run results in SARIF format to the repository Actions tab.
-      # https://docs.github.com/en/actions/advanced-guides/storing-workflow-data-as-artifacts
-      - name: "Upload artifact"
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
-        with:
-          name: SARIF file
-          path: results.sarif
-          retention-days: 5
-
-      # Upload the results to GitHub's code scanning dashboard (optional).
-      # Commenting out will disable upload of results to your repo's Code Scanning dashboard
-      - name: "Upload to code-scanning"
-        uses: github/codeql-action/upload-sarif@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
-        with:
-          sarif_file: results.sarif
+      contents: read # for actions/checkout
+      id-token: write # for Scorecard to publish results
+      security-events: write # for the SARIF upload to code scanning
+    uses: open-telemetry/shared-workflows/.github/workflows/scorecard.yml@f13d0cb656d7244ca8c1638b6996dbaef1083bdd # v0.6.0

CHANGELOG.md

@@ -15,6 +15,8 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 ### :rocket: Features
 
 * feat(resources): Deprecate `envDetector` in favor of separate `resourceAttributesEnvDetector` and `serviceNameEnvDetector`. Also mark `serviceInstanceIdDetector` as stable (the `service.instance.id` semconv attribute is now stable). [#6999](https://github.com/open-telemetry/opentelemetry-js/pull/6999) @trentm
+* feat(context-async-hooks): implement `attach()` on `AsyncLocalStorageContextManager` [#6845](https://github.com/open-telemetry/opentelemetry-js/pull/6845) @pichlermarc
+  * On Node.js 25.9+, delegates to `AsyncLocalStorage.withScope()` returning a native `RunScope`. On older Node.js, falls back to `enterWith()` with a manual disposable wrapper.
 * feat(sdk-trace): allow configuring the force flush timeout per call #6929 @LarryHu0217
 
 ### :bug: Bug Fixes
@@ -23,6 +25,7 @@ For notes on migrating to 2.x / 0.200.x see [the upgrade guide](doc/upgrade-to-2
 
 ### :house: Internal
 
+* chore(ci): run documentation tests on a weekly schedule [#6920](https://github.com/open-telemetry/opentelemetry-js/pull/6920) @LarryHu0217
 * chore(resources): Ensure that multiple uses of serviceInstanceIdDetector.detect() return the *same* value for `service.instance.id`
 
 ## 2.10.0

api/CHANGELOG.md

@@ -9,12 +9,18 @@ All notable changes to this project will be documented in this file.
 
 ### :rocket: Features
 
+* feat(api): add imperative `context.attach()` for setting context across callback boundaries that `with()` cannot wrap. [#6845](https://github.com/open-telemetry/opentelemetry-js/pull/6845) @pichlermarc
+  * `attach()` returns a `Token` whose `dispose()` method restores the previous context. Use `token.dispose()` to detach.
+  * `attach` is an optional method on the `ContextManager` interface; when the active context manager does not implement it, `context.attach()` logs a warning and returns a no-op token.
+
 ### :bug: Bug Fixes
 
 ### :books: Documentation
 
 ### :house: Internal
 
+* perf(api): add getGlobal fast-path [#6956](https://github.com/open-telemetry/opentelemetry-js/pull/6956) @legendecas
+
 ## 1.9.1
 
 ### :bug: (Bug Fix)

api/package.json

@@ -28,6 +28,7 @@
     "lint": "eslint . && npm run cycle-check",
     "test:browser": "karma start --single-run",
     "test": "nyc mocha 'test/**/*.test.ts'",
+    "test:bench": "node test/performance/benchmark/internal-benchmarks.js && node test/performance/benchmark/public-benchmarks.js | tee .benchmark-results.txt",
     "test:node8-compat": "node test/backcompat/node8-compat.js",
     "test:webworker": "karma start karma.worker.js --single-run",
     "cycle-check": "dpdm --exit-code circular:1 src/index.ts",
@@ -73,7 +74,7 @@
     "@types/webpack": "5.28.5",
     "@types/webpack-env": "1.18.8",
     "babel-plugin-istanbul": "8.0.0",
-    "dpdm": "4.2.0",
+    "dpdm": "4.3.0",
     "karma": "6.4.4",
     "karma-chrome-launcher": "3.1.0",
     "karma-coverage": "2.2.1",

api/src/api/context.ts

@@ -4,7 +4,11 @@
  */
 
 import { NoopContextManager } from '../context/NoopContextManager';
-import type { Context, ContextManager } from '../context/types';
+import type {
+  Context,
+  ContextManager,
+  ContextManagementToken,
+} from '../context/types';
 import {
   getGlobal,
   registerGlobal,
@@ -14,6 +18,9 @@ import { DiagAPI } from './diag';
 
 const API_NAME = 'context';
 const NOOP_CONTEXT_MANAGER = new NoopContextManager();
+const NOOP_TOKEN: ContextManagementToken = Object.freeze({
+  dispose: () => {},
+});
 
 /**
  * Singleton object which represents the entry point to the OpenTelemetry Context API
@@ -23,6 +30,12 @@ const NOOP_CONTEXT_MANAGER = new NoopContextManager();
 export class ContextAPI {
   private static _instance?: ContextAPI;
 
+  /**
+   * Tracks whether we have already warned that the active ContextManager does
+   * not implement attach(), so we warn at most once instead of on every call.
+   */
+  private _attachUnsupportedWarned = false;
+
   /** Empty private constructor prevents end users from constructing a new instance of the API */
   private constructor() {}
 
@@ -78,6 +91,42 @@ export class ContextAPI {
     return this._getContextManager().bind(context, target);
   }
 
+  /**
+   * Imperatively sets `context` as active, returning a {@link ContextManagementToken} whose
+   * {@link ContextManagementToken.dispose} restores the previous context.
+   *
+   * This is a delicate, low-level API - prefer {@link with}/{@link bind}, which
+   * restore context automatically. Use `attach` only to bridge callback
+   * boundaries that `with` cannot wrap. Call `token.dispose()` when the
+   * operation is done.
+   *
+   * **Caveat for async functions:** If called inside an async function before
+   * the first `await`, the context change may leak into the caller's context
+   * and remain active there. Prefer {@link with} for async code.
+   *
+   * Support is best-effort and varies by the active ContextManager (see
+   * {@link ContextManager.attach}); if it does not implement `attach`, this logs
+   * a warning and returns a no-op token.
+   *
+   * @param context The Context to attach
+   * @returns A {@link ContextManagementToken} whose dispose() restores the previous Context
+   * @since 1.10.0
+   * @experimental This API is experimental and may change in minor releases without prior notice.
+   */
+  public attach(context: Context): ContextManagementToken {
+    const contextManager = this._getContextManager();
+    if (contextManager.attach) {
+      return contextManager.attach(context);
+    }
+    if (!this._attachUnsupportedWarned) {
+      this._attachUnsupportedWarned = true;
+      DiagAPI.instance().warn(
+        'The current ContextManager does not implement attach(). The context will not be attached. Use a ContextManager that supports attach() (e.g. AsyncLocalStorageContextManager) or use with()/bind() instead.'
+      );
+    }
+    return NOOP_TOKEN;
+  }
+
   private _getContextManager(): ContextManager {
     return getGlobal(API_NAME) || NOOP_CONTEXT_MANAGER;
   }

api/src/context/NoopContextManager.ts

@@ -31,4 +31,9 @@ export class NoopContextManager implements types.ContextManager {
   disable(): this {
     return this;
   }
+
+  /** @experimental This API is experimental and may change in minor releases without prior notice. */
+  attach(_context: types.Context): types.ContextManagementToken {
+    return { dispose() {} };
+  }
 }

api/src/context/types.ts

@@ -32,6 +32,17 @@ export interface Context {
   deleteValue(key: symbol): Context;
 }
 
+/**
+ * A scope token returned by {@link ContextManager.attach} that restores the previous
+ * {@link Context} when disposed. Call `token.dispose()` to restore the previous context.
+ *
+ * @since 1.10.0
+ * @experimental This API is experimental and may change in minor releases without prior notice.
+ */
+export interface ContextManagementToken {
+  dispose(): void;
+}
+
 /**
  * @since 1.0.0
  */
@@ -71,4 +82,26 @@ export interface ContextManager {
    * Disable context management
    */
   disable(): this;
+
+  /**
+   * Imperatively sets `context` as active, returning a {@link ContextManagementToken} whose
+   * {@link ContextManagementToken.dispose} method restores the previous context.
+   *
+   * This is a delicate, low-level API - prefer {@link with}/{@link bind}, which
+   * restore context automatically. `attach` exists only to bridge callback
+   * boundaries that `with` cannot wrap. The caller is responsible for disposing
+   * the token via `token.dispose()` when the operation is complete. Support is
+   * optional and best-effort; when omitted, {@link ContextAPI.attach} logs a
+   * warning and returns a no-op token.
+   *
+   * **Caveat for async functions:** If called inside an async function before
+   * the first `await`, the context change may leak into the caller's context
+   * and remain active there. Prefer {@link with} for async code.
+   *
+   * @param context The Context to attach
+   * @returns A {@link ContextManagementToken} whose dispose() restores the previous Context
+   * @since 1.10.0
+   * @experimental This API is experimental and may change in minor releases without prior notice.
+   */
+  attach?(context: Context): ContextManagementToken;
 }

api/src/index.ts

@@ -19,7 +19,11 @@ export type { Attributes, AttributeValue } from './common/Attributes';
 
 // Context APIs
 export { createContextKey, ROOT_CONTEXT } from './context/context';
-export type { Context, ContextManager } from './context/types';
+export type {
+  Context,
+  ContextManager,
+  ContextManagementToken,
+} from './context/types';
 export type { ContextAPI } from './api/context';
 
 // Diag APIs