feat(otel): Trace decorator accepts scope

- symbol can be symbol

demo:
- test/decorator/112.docorator-scope.test.ts
- test/fixtures/base-app/src/trace.decorator/112a.decorator-scope.controller.ts

Author: waitingsong

packages/otel/README.md

@@ -100,6 +100,45 @@ export class FooController {
 }
 ```
 
+Pass `scope` to avoid the confusion of call chain relationship when async methods are called concurrently
+
+```ts
+import { Trace } from '@mwcp/otel'
+
+@Controller('/')
+export class FooController {
+
+  @Trace()
+  async hello(): Promise<string> {
+    await Promise.all([
+      this._simple1(),
+      this._simple2(),
+    ])
+    return 'OK'
+  }
+
+  @Trace({ scope: 'hello1' })
+  async _hello1(): Promise<string> {
+    return 'world'
+  }
+
+  @Trace({ scope: 'hello2' })
+  async _hello2(): Promise<string> {
+    return 'world'
+  }
+
+  @Trace({ scope: 'hello1' })
+  async _hello1a(): Promise<string> {
+    return 'world'
+  }
+
+  @Trace({ scope: 'hello2' })
+  async _hello2a(): Promise<string> {
+    return 'world'
+  }
+}
+```
+
 ## `TraceInit` Decorator
 
 ```ts

packages/otel/README.zh-CN.md

@@ -100,6 +100,45 @@ export class FooController {
 }
 ```
 
+使用 `scope` 避免异步方法并发请求时调用链混乱
+
+```ts
+import { Trace } from '@mwcp/otel'
+
+@Controller('/')
+export class FooController {
+
+  @Trace()
+  async hello(): Promise<string> {
+    await Promise.all([
+      this._simple1(),
+      this._simple2(),
+    ])
+    return 'OK'
+  }
+
+  @Trace({ scope: 'hello1' })
+  async _hello1(): Promise<string> {
+    return 'world'
+  }
+
+  @Trace({ scope: 'hello2' })
+  async _hello2(): Promise<string> {
+    return 'world'
+  }
+
+  @Trace({ scope: 'hello1' })
+  async _hello1a(): Promise<string> {
+    return 'world'
+  }
+
+  @Trace({ scope: 'hello2' })
+  async _hello2a(): Promise<string> {
+    return 'world'
+  }
+}
+```
+
 ## `TraceInit` 装饰器
 
 ```ts

packages/otel/src/lib/abstract.ts

@@ -140,6 +140,7 @@ export abstract class AbstractTraceService {
     name: string,
     options?: SpanOptions,
     traceContext?: Context,
+    scope?: object | symbol,
   ): Span
 
   /**
@@ -161,6 +162,7 @@ export abstract class AbstractTraceService {
     callback: F,
     options?: SpanOptions,
     traceContext?: Context,
+    scope?: object | symbol,
   ): ReturnType<F>
 
   /**
@@ -231,7 +233,7 @@ export interface StartScopeActiveSpanOptions {
   /**
    * @default scope is `this.ctx`
    */
-  scope?: object
+  scope?: object | symbol | undefined
   spanOptions?: SpanOptions | undefined
   traceContext?: Context | undefined
 }

packages/otel/src/lib/component.ts

@@ -84,7 +84,9 @@ export class OtelComponent extends AbstractOtelComponent {
   otelLibraryVersion: string
   /* request|response -> Map<lower,norm> */
   readonly captureHeadersMap = new Map<string, Map<string, string>>()
-  readonly traceContextMap = new WeakMap<object, Context[]>()
+  // ref: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WeakMap
+  // @ts-expect-error non-registered symbols can be used as keys
+  readonly traceContextMap = new WeakMap<object | symbol, Context[]>()
 
   protected traceProvider: node.NodeTracerProvider | undefined
   protected spanProcessors: node.SpanProcessor[] = []
@@ -410,17 +412,19 @@ export class OtelComponent extends AbstractOtelComponent {
     }
   }
 
-  getScopeActiveContext(scope: object): Context | undefined {
+  getScopeActiveContext(scope: object | symbol): Context | undefined {
     if (! this.config.enable) { return }
 
-    assert(typeof scope === 'object', 'scope must be an object')
+    const tp = typeof scope
+    assert(tp === 'object' || tp === 'symbol', 'scope must be an object or symbol')
+
     const arr = this.traceContextMap.get(scope)
     if (arr?.length) {
       return this.getActiveContextFromArray(arr)
     }
   }
 
-  setScopeActiveContext(scope: object, ctx: Context): void {
+  setScopeActiveContext(scope: object | symbol, ctx: Context): void {
     if (! this.config.enable) { return }
 
     const currCtx = this.getScopeActiveContext(scope)
@@ -434,10 +438,12 @@ export class OtelComponent extends AbstractOtelComponent {
     this.traceContextMap.set(scope, [ctx])
   }
 
-  delScopeActiveContext(scope: object): void {
+  delScopeActiveContext(scope: object | symbol): void {
     if (! this.config.enable) { return }
 
-    assert(typeof scope === 'object', 'scope must be an object')
+    const tp = typeof scope
+    assert(tp === 'object' || tp === 'symbol', 'scope must be an object or symbol')
+
     const arr = this.traceContextMap.get(scope)
     if (arr) {
       arr.length = 0

packages/otel/src/lib/decorator.helper.ts

@@ -4,9 +4,16 @@ import { isPromise } from 'node:util/types'
 import type { Span } from '@opentelemetry/api'
 
 import type { AbstractOtelComponent, AbstractTraceService } from './abstract.js'
-import type { DecoratorContext, DecoratorTraceDataResp, TraceDecoratorOptions } from './decorator.types.js'
+import type {
+  DecoratorContext,
+  DecoratorContextBase,
+  DecoratorTraceDataResp,
+  ScopeGenerator,
+  TraceDecoratorOptions,
+} from './decorator.types.js'
 import { DecoratorExecutorParam } from './trace.helper.js'
 import { AttrNames } from './types.js'
+import { isSpanEnded } from './util.js'
 
 
 export async function processDecoratorBeforeAfterAsync(
@@ -20,19 +27,15 @@ export async function processDecoratorBeforeAfterAsync(
 
   const func = mergedDecoratorParam?.[type]
   if (typeof func === 'function') {
-    // @ts-expect-error
-    if (typeof span.ended === 'function') {
-      // @ts-expect-error
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-      assert(! span.ended(), 'span is ended after method call')
-    }
+    assert(! isSpanEnded(span), 'span is ended after method call')
     const decoratorContext: DecoratorContext = {
       webApp: options.webApp,
       webContext: options.webContext,
       otelComponent: options.otelComponent,
       traceService: options.traceService,
       traceContext: options.traceContext,
       traceSpan: span,
+      // instance: options.instance,
     }
 
     let data
@@ -67,12 +70,7 @@ export function processDecoratorBeforeAfterSync(
 
   const func = mergedDecoratorParam?.[type]
   if (typeof func === 'function') {
-    // @ts-expect-error
-    if (typeof span.ended === 'function') {
-      // @ts-expect-error
-      // eslint-disable-next-line @typescript-eslint/no-unsafe-call
-      assert(! span.ended(), 'span is ended after method call')
-    }
+    assert(! isSpanEnded(span), 'span is ended after method call')
     const decoratorContext: DecoratorContext = {
       webApp: options.webApp,
       webContext: options.webContext,
@@ -150,3 +148,76 @@ function processDecoratorSpanData(
     }
   }
 }
+
+export function genTraceScopeFrom(options: DecoratorExecutorParam): object | symbol | undefined {
+  const { mergedDecoratorParam } = options
+
+  let scope
+  if (mergedDecoratorParam?.scope) {
+    const decoratorContextBase: DecoratorContextBase = {
+      webApp: options.webApp,
+      webContext: options.webContext,
+      otelComponent: options.otelComponent,
+      traceService: options.traceService,
+      // instance: options.instance,
+    }
+    scope = genTraceScope({
+      scope: mergedDecoratorParam.scope,
+      methodArgs: options.methodArgs,
+      decoratorContext: decoratorContextBase,
+    })
+  }
+  return scope
+}
+
+const traceScopeStringCache = new Map<string, symbol>()
+function getScopeStringCache(key: string): symbol {
+  let sym = traceScopeStringCache.get(key)
+  if (! sym) {
+    sym = Symbol(key)
+    setScopeStringCache(key, sym)
+  }
+  return sym
+}
+function setScopeStringCache(key: string, sym: symbol): void {
+  /* c8 ignore next 3 */
+  if (traceScopeStringCache.size > 10000) {
+    console.warn('traceScopeStringCache.size > 10000, should clear it')
+  }
+  traceScopeStringCache.set(key, sym)
+}
+
+export interface GenTraceScopeOptions {
+  scope: TraceDecoratorOptions['scope']
+  methodArgs: unknown[]
+  decoratorContext: DecoratorContextBase
+}
+export function genTraceScope(options: GenTraceScopeOptions): object | symbol | undefined {
+  const { scope } = options
+  switch (typeof scope) {
+    case 'string':
+      // Symbol.for() invalid as key of WeakMap
+      return getScopeStringCache(scope)
+
+    case 'object':
+      return scope
+
+    case 'undefined':
+      return
+
+    case 'function': {
+      const res = (scope as ScopeGenerator)(options.methodArgs, options.decoratorContext)
+      assert(typeof res === 'object' || typeof res === 'symbol', 'scope function must return an object or a symbol')
+      return res
+    }
+
+    case 'symbol':
+      return scope
+
+    /* c8 ignore next 2 */
+    default:
+      throw new Error('scope must be a string, an object, a symbol, or a function')
+  }
+
+}
+

packages/otel/src/lib/decorator.trace/trace.helper.async.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert'
 
-import { processDecoratorBeforeAfterAsync } from '../decorator.helper.js'
+import { processDecoratorBeforeAfterAsync, genTraceScopeFrom } from '../decorator.helper.js'
 import type { DecoratorExecutorParam } from '../trace.helper.js'
 import { ConfigKey } from '../types.js'
 
@@ -18,6 +18,7 @@ export async function beforeAsync(options: DecoratorExecutorParam): Promise<void
   if (! traceService) { return }
 
   const type = 'before'
+  const scope = genTraceScopeFrom(options)
 
   if (startActiveSpan) {
     // await traceService.startActiveSpan(
@@ -30,15 +31,15 @@ export async function beforeAsync(options: DecoratorExecutorParam): Promise<void
     //   spanOptions,
     //   traceContext,
     // )
-    options.span = traceService.startScopeActiveSpan({ name: spanName, spanOptions, traceContext })
+    options.span = traceService.startScopeActiveSpan({ name: spanName, spanOptions, traceContext, scope })
     options.span.setAttributes(callerAttr)
     return processDecoratorBeforeAfterAsync(type, options)
   }
   else {
     // it's necessary to cost a little time to prevent next span.startTime is same as previous span.endTime
     const rndStr = Math.random().toString(36).substring(7)
     void rndStr
-    options.span = traceService.startSpan(spanName, spanOptions, traceContext)
+    options.span = traceService.startSpan(spanName, spanOptions, traceContext, scope)
     options.span.setAttributes(callerAttr)
     return processDecoratorBeforeAfterAsync(type, options)
   }

packages/otel/src/lib/decorator.trace/trace.helper.sync.ts

@@ -3,7 +3,7 @@ import { isAsyncFunction } from 'util/types'
 
 import { ConfigKey } from '@mwcp/share'
 
-import { processDecoratorBeforeAfterSync } from '../decorator.helper.js'
+import { genTraceScopeFrom, processDecoratorBeforeAfterSync } from '../decorator.helper.js'
 import type { DecoratorExecutorParam } from '../trace.helper.js'
 import { AttrNames } from '../types.js'
 
@@ -28,6 +28,7 @@ export function beforeSync(options: DecoratorExecutorParam): void {
     `[@mwcp/${ConfigKey.namespace}] Trace() ${type}() is a AsyncFunction, but decorated method is sync function, class: ${callerAttr[AttrNames.CallerClass]}, method: ${callerAttr[AttrNames.CallerMethod]}`,
   )
   assert(spanName, 'spanName is empty')
+  const scope = genTraceScopeFrom(options)
 
   if (startActiveSpan) {
     // traceService.startActiveSpan(
@@ -40,15 +41,15 @@ export function beforeSync(options: DecoratorExecutorParam): void {
     //   spanOptions,
     //   traceContext,
     // )
-    options.span = traceService.startScopeActiveSpan({ name: spanName, spanOptions, traceContext })
+    options.span = traceService.startScopeActiveSpan({ name: spanName, spanOptions, traceContext, scope })
     options.span.setAttributes(callerAttr)
     processDecoratorBeforeAfterSync(type, options)
   }
   else {
     // it's necessary to cost a little time to prevent next span.startTime is same as previous span.endTime
     const rndStr = Math.random().toString(36).substring(7)
     void rndStr
-    options.span = traceService.startSpan(spanName, spanOptions, traceContext)
+    options.span = traceService.startSpan(spanName, spanOptions, traceContext, scope)
     options.span.setAttributes(callerAttr)
     processDecoratorBeforeAfterSync(type, options)
   }