fix: (observability) make async/await correctly work by setting initial AsyncHooksManager

[odeke-em]

OpenTelemetry cannot work correctly for async/await if there isn't a set AsyncHooksManager, but we should not burden our customers with this type of specialist knowledge, their code should just work and this change performs such a check. Later on we shall file a feature request with the OpenTelemetry-JS API group to give us a hook to detect if we've got a live asyncHooksManager instead of this mandatory comparison to ROOT_CONTEXT each time.

Fixes #2146

[conventional-commit-lint-gcf]

🤖 I detect that the PR title and the commit message differ and there's only one commit. To use the PR title for the commit history, you can use Github's automerge feature with squashing, or use automerge label. Good luck human!

-- conventional-commit-lint bot
https://conventionalcommits.org/

[odeke-em]

Kindly help me run the bots @surbhigarg92 @alkatrivedi @harshachinta.

[surbhigarg92]

Suggested change

	/*
	* This function ensures that async/await functions correctly by
	* checking if context.active() returns an invalid/unset context
	* and if so, sets a global AsyncHooksContextManager.
	*/
	/**
	* Ensures that an appropriate Context Manager is set to support proper
	* context propagation when using async/await, particularly in OpenTelemetry.
	*
	* OpenTelemetry's context system relies on `context.active()` to retrieve the
	* current active context. However, if this returns the default `ROOT_CONTEXT`,
	* it indicates that no context has been previously set. Without a valid context,
	* async/await calls will fail to propagate context correctly, which can cause
	* issues in distributed tracing and telemetry data collection.
	*
	* This function checks if the active context is invalid (i.e., `ROOT_CONTEXT`).
	* If so, it resets the Context Manager by disabling any prior manager and then
	* enabling a new instance of `AsyncHooksContextManager` to properly track async
	* operations and context propagation.
	*
	* The goal is to ensure that users' code works seamlessly with OpenTelemetry,
	* without requiring them to modify their existing code to manually manage context.
	*
	* Further details:
	* - OpenTelemetry context documentation: https://opentelemetry.io/docs/languages/js/context/#active-context
	* - Related issue: https://github.com/googleapis/nodejs-spanner/issues/2146
	*/

[surbhigarg92]

@odeke-em I generated this documentation using AI, please review once more. But we need a more structured documentation

[odeke-em]

Some of this AI generated documentation is not correct like

 * The goal is to ensure that users' code works seamlessly with OpenTelemetry, 
* without requiring them to modify their existing code to manually manage context.

it's nothing about manually managing context but setting a global context manager.

[odeke-em]

@surbhigarg92 the generated AI comments instead just is listing out what the function does but not really why and the purpose of the code which is to check if there was any already set contextManager and if not, set one.

[surbhigarg92]

Suggested change

	// If no active context was set previously, trace context propagation cannot
	// work correctly with async/await for OpenTelemetry and they acknowledge
	// this fact per https://opentelemetry.io/docs/languages/js/context/#active-context
	// but we shouldn't make our customers have to invasively edit their code
	// nor should they be burdened about these facts, their code should JUST work.
	// Please see https://github.com/googleapis/nodejs-spanner/issues/2146
	// No active context set, so context propagation won't work with async/await.
	// Fix by disabling any prior context manager and setting a new AsyncHooksContextManager.

[surbhigarg92]

Use a better name for this. If you are testing "async/await" use name like Observability tests with async/await

[odeke-em]

I'd highly encourage keeping such a section for known and fixed regressions with isolated test cases, otherwise eventually we'll just have a pile up of test cases that we don't have a single reference to.

[odeke-em]

This is the section in which we shall be inserting all regression tests and bug fixes.

[odeke-em]

I tweaked it, please take a look.

[odeke-em]

Kindly help me run the bots @alkatrivedi @surbhigarg92 @harshachinta

[odeke-em]

I've instead moved the fix into one PR #2145 because it takes 3+ hours just to run tests, 1+ day for 1 PR code reviews but we don't have much time.