perf(api): add getGlobal fast-path

[legendecas]

Which problem is this PR solving?

In examples, documents and instrumentations, we use patterns like api.context.active() and api.trace.setSpan(...) a lot. However, the isCompatible check could be expensive even if it caches the version with a Set.has if the call count accumulates.

This adds a fast-path where the global api is rarely modified, as API registration happens way less frequent than getGlobal(). API registration usually only happens at startup time once.

One caveat is that this assumes that no one tries to modify the global[GLOBAL_OPENTELEMETRY_API_KEY].version on the same object global[GLOBAL_OPENTELEMETRY_API_KEY]. The @opentelemetry/api package itself does not do this, so the fast-path is compatible with existing @opentelemetry/api versions. This also seals the global[GLOBAL_OPENTELEMETRY_API_KEY].version to be non-writable and non-configurable to make sure that fast-path is always correct.

┌───────────────────────────┬───────────┬────────────┬─────────────┐
│         Benchmark         │ Main      │   New      │ Improvement │
├───────────────────────────┼───────────┼────────────┼─────────────┤
│ getGlobal (registered)    │ 3,372,280 │ 16,076,095 │ +377%       │
├───────────────────────────┼───────────┼────────────┼─────────────┤
│ getGlobal (unregistered)  │ 3,725,912 │ 21,017,474 │ +464%       │
├───────────────────────────┼───────────┼────────────┼─────────────┤
│ context.active()          │ 3,423,831 │ 10,616,871 │ +210%       │
├───────────────────────────┼───────────┼────────────┼─────────────┤
│ trace.getTracerProvider() │ 3,324,899 │ 12,627,415 │ +280%       │
└───────────────────────────┴───────────┴────────────┴─────────────┘

Type of change

• Bug fix (non-breaking change which fixes an issue)

How Has This Been Tested?

• All existing tests should pass
• Verify that if someone installs null to the global[GLOBAL_OPENTELEMETRY_API_KEY].

Checklist:

• Followed the style guidelines of this project
• Unit tests have been added
• Documentation has been updated

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-07-28 23:30 UTC

Review the latest changes.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.07%. Comparing base (636e27a) to head (643e5a4).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6956   +/-   ##
=======================================
  Coverage   95.07%   95.07%           
=======================================
  Files         409      409           
  Lines       14256    14262    +6     
  Branches     3267     3266    -1     
=======================================
+ Hits        13554    13560    +6     
  Misses        702      702           

Files with missing lines	Coverage Δ
api/src/internal/global-utils.ts	84.44% <100.00%> (+2.39%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.