Are there node.js examples for async/promises based functions?

[jwatte]

All the examples for node.js just use a synchronous "die roller" application.
Most real applications are based on async functions and promises, and the "scoped" callback-based tracer.startActiveSpan() function will end the span too early.
There are some discussion about how (synchronous) callbacks are bad style in Node.js (which is true within the context of promises based functions) but the answers are all missing the point, saying "functions aren't bad style."

So, are there really no async-based helpers in the opentelemetry SDK?
What is the recommended way to trace async functions?

[LarryHu0217]

startActiveSpan() works with an async callback. The callback style does not require the work itself to be synchronous: the method returns the callback's return value, so an async callback produces a Promise that you can await.

import { SpanStatusCode, trace } from '@opentelemetry/api';

const tracer = trace.getTracer('my-service');

async function tracedOperation() {
  return await tracer.startActiveSpan('operation', async (span) => {
    try {
      const result = await doAsyncWork();
      return result;
    } catch (error) {
      span.recordException(error as Error);
      span.setStatus({ code: SpanStatusCode.ERROR });
      throw error;
    } finally {
      span.end();
    }
  });
}

The important distinction is that startActiveSpan() does not automatically end the span when the callback returns. Calling span.end() in finally makes it happen after the awaited operation succeeds or fails.

The current API type returns ReturnType<F>, and the implementation returns context.with(...) directly:

• opentelemetry-js/api/src/trace/tracer.ts

  Lines 29 to 95 in b2ffd97

  	*/
  	startSpan(name: string, options?: SpanOptions, context?: Context): Span;
  	/**
  	* Starts a new {@link Span} and calls the given function passing it the
  	* created span as first argument.
  	* Additionally the new span gets set in context and this context is activated
  	* for the duration of the function call.
  	*
  	* **Important**: The callback function is responsible for calling `span.end()`
  	* to finish the span. Unlike some other OpenTelemetry implementations, the span
  	* is NOT automatically ended when the callback returns. If `span.end()` is not
  	* called, the span will never be exported and will be silently lost.
  	*
  	* @param name The name of the span
  	* @param [options] SpanOptions used for span creation
  	* @param [context] Context to use to extract parent
  	* @param fn function called in the context of the span and receives the newly created span as an argument
  	* @returns return value of fn
  	* @example
  	* const something = tracer.startActiveSpan('op', span => {
  	* try {
  	* do some work
  	* span.setStatus({code: SpanStatusCode.OK});
  	* return something;
  	* } catch (err) {
  	* span.setStatus({
  	* code: SpanStatusCode.ERROR,
  	* message: err.message,
  	* });
  	* throw err;
  	* } finally {
  	* span.end();
  	* }
  	* });
  	*
  	* @example
  	* const span = tracer.startActiveSpan('op', span => {
  	* try {
  	* do some work
  	* return span;
  	* } catch (err) {
  	* span.setStatus({
  	* code: SpanStatusCode.ERROR,
  	* message: err.message,
  	* });
  	* throw err;
  	* }
  	* });
  	* do some more work
  	* span.end();
  	*/
  	startActiveSpan<F extends (span: Span) => unknown>(
  	name: string,
  	fn: F
  	): ReturnType<F>;
  	startActiveSpan<F extends (span: Span) => unknown>(
  	name: string,
  	options: SpanOptions,
  	fn: F
  	): ReturnType<F>;
  	startActiveSpan<F extends (span: Span) => unknown>(
  	name: string,
  	options: SpanOptions,
  	context: Context,
  	fn: F
  	): ReturnType<F>;

• opentelemetry-js/packages/sdk-trace/src/Tracer.ts

  Lines 210 to 251 in b2ffd97

  	name: string,
  	fn: F
  	): ReturnType<F>;
  	startActiveSpan<F extends (span: api.Span) => ReturnType<F>>(
  	name: string,
  	opts: api.SpanOptions,
  	fn: F
  	): ReturnType<F>;
  	startActiveSpan<F extends (span: api.Span) => ReturnType<F>>(
  	name: string,
  	opts: api.SpanOptions,
  	ctx: api.Context,
  	fn: F
  	): ReturnType<F>;
  	startActiveSpan<F extends (span: api.Span) => ReturnType<F>>(
  	name: string,
  	arg2?: F | api.SpanOptions,
  	arg3?: F | api.Context,
  	arg4?: F
  	): ReturnType<F> | undefined {
  	let opts: api.SpanOptions | undefined;
  	let ctx: api.Context | undefined;
  	let fn: F;
  	if (arguments.length < 2) {
  	return;
  	} else if (arguments.length === 2) {
  	fn = arg2 as F;
  	} else if (arguments.length === 3) {
  	opts = arg2 as api.SpanOptions | undefined;
  	fn = arg3 as F;
  	} else {
  	opts = arg2 as api.SpanOptions | undefined;
  	ctx = arg3 as api.Context | undefined;
  	fn = arg4 as F;
  	}
  	const parentContext = ctx ?? api.context.active();
  	const span = this.startSpan(name, opts, parentContext);
  	const contextWithSpanSet = api.trace.setSpan(parentContext, span);
  	return api.context.with(contextWithSpanSet, fn, undefined, span);

On Node.js, NodeTracerProvider.register() installs AsyncLocalStorageContextManager by default, so child spans created by async resources inside that callback retain the active parent context:

opentelemetry-js/packages/opentelemetry-sdk-trace-node/src/NodeTracerProvider.ts

Lines 17 to 34 in b2ffd97

	function setupContextManager(
	contextManager: ContextManager | null | undefined
	) {
	// null means 'do not register'
	if (contextManager === null) {
	return;
	}
	// undefined means 'register default'
	if (contextManager === undefined) {
	const defaultContextManager = new AsyncLocalStorageContextManager();
	defaultContextManager.enable();
	context.setGlobalContextManager(defaultContextManager);
	return;
	}
	contextManager.enable();
	context.setGlobalContextManager(contextManager);

Initialize and register the SDK before loading the application modules that create async work. If using BasicTracerProvider directly instead of the Node provider/Node SDK, register an async context manager yourself; otherwise the active-context part will not propagate correctly.