vona-module-a-telemetry 5.0.1

package/dist/service/telemetry.d.ts

@@ -0,0 +1,31 @@
+import type { Context, Span, SpanOptions } from '@opentelemetry/api';
+import { BeanBase } from 'vona';
+import type { ITelemetryCarrier } from '../types/telemetry.ts';
+export declare class ServiceTelemetry extends BeanBase {
+    private _provider?;
+    private _contextManager?;
+    private _isTrustedIngress?;
+    private _enabled;
+    get enabled(): boolean;
+    init(): void;
+    close(forceFlush: boolean): Promise<void>;
+    get activeContext(): Context;
+    extractCarrier(carrier?: ITelemetryCarrier): Context;
+    isTrustedIngress(peerAddress?: string, internalHeaderValue?: string): boolean;
+    extractHttpIngressCarrier(trusted: boolean, carrier: ITelemetryCarrier): Context;
+    injectCarrier(source?: Context): ITelemetryCarrier;
+    startSpan(name: string, options?: SpanOptions, parent?: Context): Span;
+    withSpan<RESULT>(span: Span, fn: () => RESULT): RESULT;
+    createContext(span: Span, parent?: Context): Context;
+    recordException(span: Span, error: unknown): void;
+    endHttpSpan(span: Span, statusCode: number, aborted?: boolean): void;
+    getLogContext(): {
+        request_id: string | undefined;
+        trace_id: string;
+        span_id: string;
+        trace_flags: number;
+    } | undefined;
+    createServerSpan(method: string, parent: Context): Span;
+    enrichHttpSpan(method: string, routePath: string, controllerBeanFullName: string, action: string): void;
+}
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/service/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/service/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAarE,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAGhC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAsB/D,qBACa,gBAAiB,SAAQ,QAAQ;IAC5C,OAAO,CAAC,SAAS,CAAC,CAAqB;IACvC,OAAO,CAAC,eAAe,CAAC,CAAkC;IAC1D,OAAO,CAAC,iBAAiB,CAAC,CAAkE;IAC5F,OAAO,CAAC,QAAQ,CAAS;IAEzB,IAAI,OAAO,YAEV;IAED,IAAI;IAgCE,KAAK,CAAC,UAAU,EAAE,OAAO;IAgB/B,IAAI,aAAa,YAEhB;IAED,cAAc,CAAC,OAAO,CAAC,EAAE,iBAAiB;IAK1C,gBAAgB,CAAC,WAAW,CAAC,EAAE,MAAM,EAAE,mBAAmB,CAAC,EAAE,MAAM;IAKnE,yBAAyB,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB;IAItE,aAAa,CAAC,MAAM,UAAqB,GAAG,iBAAiB;IAM7D,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,UAAqB;IAI1E,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,MAAM,GAAG,MAAM;IAKtD,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,UAAqB;IAIrD,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO;IAS1C,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,UAAQ;IAY3D,aAAa;;;;;;IAYb,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAIhD,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,sBAAsB,EAAE,MAAM,EAC9B,MAAM,EAAE,MAAM;CAWjB"}

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './telemetry.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/types/telemetry.d.ts

@@ -0,0 +1,20 @@
+import type { Context, Span } from '@opentelemetry/api';
+export interface ITelemetryCarrier {
+    version: 1;
+    traceparent?: string;
+    tracestate?: string;
+}
+export interface ITelemetryContextState {
+    requestId?: string;
+    context?: Context;
+    span?: Span;
+    serverSpan?: Span;
+    internalAction?: boolean;
+    serverSpanEnded?: boolean;
+}
+declare module 'vona' {
+    interface ContextState {
+        telemetry?: ITelemetryContextState;
+    }
+}
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/types/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/types/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,CAAC,CAAC;IACX,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,OAAO,QAAQ,MAAM,CAAC;IACpB,UAAiB,YAAY;QAC3B,SAAS,CAAC,EAAE,sBAAsB,CAAC;KACpC;CACF"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "vona-module-a-telemetry",
+  "version": "5.0.1",
+  "description": "",
+  "keywords": [
+    "Vona Module"
+  ],
+  "author": "",
+  "files": [
+    "assets",
+    "dist",
+    "src"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": [
+        "./src/index.ts",
+        "./dist/index.d.ts"
+      ],
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "clean": "rimraf dist tsconfig.build.tsbuildinfo",
+    "tsc:publish": "npm run clean && node ../../../../../packages-cli/cli/src/bin/vona.ts :bin:buildModule --sourcemap && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run tsc:publish",
+    "prepack": "clean-package",
+    "postpack": "clean-package restore"
+  },
+  "dependencies": {
+    "@eggjs/ip": "^2.1.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/context-async-hooks": "^2.10.0",
+    "@opentelemetry/core": "^2.10.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.221.0",
+    "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.10.0",
+    "@opentelemetry/semantic-conventions": "^1.43.0"
+  },
+  "title": "a-telemetry",
+  "vonaModule": {
+    "dependencies": {
+      "a-aspect": "5.0.0",
+      "a-logger": "5.0.0"
+    }
+  },
+  "gitHead": "fac7768bb7db22ff0180dc59d711efba5b853ae7"
+}

package/src/.metadata/index.ts

@@ -0,0 +1,132 @@
+// eslint-disable
+/** middlewareSystem: begin */
+export * from '../bean/middlewareSystem.trace.ts';
+import type { IMiddlewareSystemOptionsTrace } from '../bean/middlewareSystem.trace.ts';
+import 'vona-module-a-aspect';
+declare module 'vona-module-a-aspect' {
+  
+    export interface IMiddlewareSystemRecord {
+      'a-telemetry:trace': IMiddlewareSystemOptionsTrace;
+    }
+
+  
+}
+declare module 'vona-module-a-telemetry' {
+  
+        export interface MiddlewareSystemTrace {
+          /** @internal */
+          get scope(): ScopeModuleATelemetry;
+        }
+
+          export interface MiddlewareSystemTrace {
+            get $beanFullName(): 'a-telemetry.middlewareSystem.trace';
+            get $onionName(): 'a-telemetry:trace';
+            get $onionOptions(): IMiddlewareSystemOptionsTrace;
+          } 
+}
+/** middlewareSystem: end */
+/** bean: begin */
+export * from '../bean/bean.telemetry.ts';
+
+import 'vona';
+declare module 'vona' {
+  
+  
+}
+declare module 'vona-module-a-telemetry' {
+  
+        export interface BeanTelemetry {
+          /** @internal */
+          get scope(): ScopeModuleATelemetry;
+        } 
+}
+/** bean: end */
+/** bean: begin */
+import type { BeanTelemetry } from '../bean/bean.telemetry.ts';
+import 'vona';
+declare module 'vona' {
+  export interface IBeanRecordGlobal {
+    'telemetry': BeanTelemetry;
+  }
+}
+/** bean: end */
+/** service: begin */
+export * from '../service/telemetry.ts';
+
+import 'vona-module-a-bean';
+declare module 'vona-module-a-bean' {
+  
+    export interface IServiceRecord {
+      'a-telemetry:telemetry': never;
+    }
+
+  
+}
+declare module 'vona-module-a-telemetry' {
+  
+        export interface ServiceTelemetry {
+          /** @internal */
+          get scope(): ScopeModuleATelemetry;
+        }
+
+          export interface ServiceTelemetry {
+            get $beanFullName(): 'a-telemetry.service.telemetry';
+            get $onionName(): 'a-telemetry:telemetry';
+            
+          } 
+}
+/** service: end */
+/** service: begin */
+import type { ServiceTelemetry } from '../service/telemetry.ts';
+export interface IModuleService {
+  'telemetry': ServiceTelemetry;
+}
+/** service: end */
+/** service: begin */
+
+import 'vona';
+declare module 'vona' {
+  export interface IBeanRecordGeneral {
+    'a-telemetry.service.telemetry': ServiceTelemetry;
+  }
+}
+/** service: end */
+/** config: begin */
+export * from '../config/config.ts';
+import type { config } from '../config/config.ts';
+/** config: end */
+/** monkey: begin */
+export * from '../monkey.ts';
+/** monkey: end */
+/** scope: begin */
+import { BeanScopeBase, type BeanScopeUtil, type TypeModuleConfig } from 'vona';
+import { Scope } from 'vona-module-a-bean';
+
+@Scope()
+export class ScopeModuleATelemetry extends BeanScopeBase {}
+
+export interface ScopeModuleATelemetry {
+  util: BeanScopeUtil;
+config: TypeModuleConfig<typeof config>;
+service: IModuleService;
+}
+
+import 'vona';
+declare module 'vona' {
+  export interface IBeanScopeRecord {
+    'a-telemetry': ScopeModuleATelemetry;
+  }
+
+  export interface IBeanScopeContainer {
+    telemetry: ScopeModuleATelemetry;
+  }
+  
+  export interface IBeanScopeConfig {
+    'a-telemetry': ReturnType<typeof config>;
+  }
+
+  
+
+  
+}
+/** scope: end */

package/src/.metadata/this.ts

@@ -0,0 +1,2 @@
+export const __ThisModule__ = 'a-telemetry';
+export { ScopeModuleATelemetry as ScopeModule } from './index.ts';

package/src/bean/bean.telemetry.ts

@@ -0,0 +1,71 @@
+import type { Span, SpanOptions } from '@opentelemetry/api';
+
+import { INVALID_SPAN_CONTEXT, trace } from '@opentelemetry/api';
+import { BeanBase } from 'vona';
+import { Bean } from 'vona-module-a-bean';
+
+const nonRecordingSpan = trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
+
+@Bean()
+export class BeanTelemetry extends BeanBase {
+  get enabled() {
+    return this.scope.service.telemetry.enabled;
+  }
+
+  startSpan(name: string, options?: SpanOptions): Span {
+    const telemetry = this.scope.service.telemetry;
+    return telemetry.enabled ? telemetry.startSpan(name, options) : nonRecordingSpan;
+  }
+
+  withSpan<RESULT>(span: Span, fn: () => RESULT): RESULT {
+    const telemetry = this.scope.service.telemetry;
+    return telemetry.enabled ? telemetry.withSpan(span, fn) : fn();
+  }
+
+  recordException(span: Span, error: unknown) {
+    const telemetry = this.scope.service.telemetry;
+    if (telemetry.enabled) telemetry.recordException(span, error);
+  }
+
+  withNamedSpan<RESULT>(name: string, fn: () => RESULT, options?: SpanOptions): RESULT {
+    const span = this.startSpan(name, options);
+    try {
+      const result = this.withSpan(span, fn);
+      if (isPromiseLike(result)) {
+        return result.then(
+          value => {
+            this._endSpan(span);
+            return value;
+          },
+          error => {
+            this._recordAndEndSpan(span, error);
+            throw error;
+          },
+        ) as RESULT;
+      }
+      this._endSpan(span);
+      return result;
+    } catch (error) {
+      this._recordAndEndSpan(span, error);
+      throw error;
+    }
+  }
+
+  private _recordAndEndSpan(span: Span, error: unknown) {
+    try {
+      this.recordException(span, error);
+    } catch {}
+    this._endSpan(span);
+  }
+
+  private _endSpan(span: Span) {
+    try {
+      span.end();
+    } catch {}
+  }
+}
+
+function isPromiseLike<RESULT>(value: RESULT): value is RESULT & PromiseLike<Awaited<RESULT>> {
+  if (!((typeof value === 'object' && value !== null) || typeof value === 'function')) return false;
+  return typeof (value as { then?: unknown }).then === 'function';
+}

package/src/bean/middlewareSystem.trace.ts

@@ -0,0 +1,73 @@
+import type { Span } from '@opentelemetry/api';
+import type { Next } from 'vona';
+import type {
+  IDecoratorMiddlewareSystemOptions,
+  IMiddlewareSystemExecute,
+} from 'vona-module-a-aspect';
+
+import { context } from '@opentelemetry/api';
+import { BeanBase, uuidv4 } from 'vona';
+import { MiddlewareSystem } from 'vona-module-a-aspect';
+
+export interface IMiddlewareSystemOptionsTrace extends IDecoratorMiddlewareSystemOptions {}
+
+@MiddlewareSystem<IMiddlewareSystemOptionsTrace>({
+  dependents: 'a-logger:httpLog',
+})
+export class MiddlewareSystemTrace extends BeanBase implements IMiddlewareSystemExecute {
+  async execute(_options: IMiddlewareSystemOptionsTrace, next: Next) {
+    const telemetry = this.$scope.telemetry.service.telemetry;
+    if (!telemetry.enabled || this.ctx.state.telemetry?.internalAction) return next();
+
+    const ctx = this.ctx;
+    const config = telemetry.scope.config;
+    const requestIdHeader = config.requestIdHeader;
+    const requestId = normalizeRequestId(ctx.get(requestIdHeader)) ?? uuidv4();
+    const trustedIngress = telemetry.isTrustedIngress(
+      ctx.req.socket.remoteAddress,
+      ctx.get(config.ingress.internalHeader),
+    );
+    const parent = telemetry.extractHttpIngressCarrier(trustedIngress, {
+      version: 1,
+      traceparent: ctx.get('traceparent') || undefined,
+      tracestate: ctx.get('tracestate') || undefined,
+    });
+    const span = telemetry.createServerSpan(ctx.method, parent);
+    const active = telemetry.createContext(span, parent);
+    ctx.state.telemetry = { requestId, context: active, serverSpan: span };
+    ctx.set(requestIdHeader, requestId);
+
+    const finish = () => this._end(span, ctx.res.statusCode || ctx.status || 500, false);
+    const close = () =>
+      this._end(span, ctx.res.statusCode || ctx.status || 499, !ctx.res.writableEnded);
+    ctx.res.once('finish', finish);
+    ctx.res.once('close', close);
+
+    try {
+      const result = await context.with(active, next);
+      if (ctx.route) {
+        telemetry.enrichHttpSpan(
+          ctx.route.routeMethod,
+          ctx.route.routePathRaw,
+          ctx.route.controllerBeanFullName,
+          ctx.route.action,
+        );
+      }
+      return result;
+    } catch (err) {
+      telemetry.recordException(span, err);
+      throw err;
+    }
+  }
+
+  private _end(span: Span, statusCode: number, aborted: boolean) {
+    if (!span || this.ctx.state.telemetry?.serverSpanEnded) return;
+    this.ctx.state.telemetry!.serverSpanEnded = true;
+    this.$scope.telemetry.service.telemetry.endHttpSpan(span, statusCode, aborted);
+  }
+}
+
+function normalizeRequestId(value?: string) {
+  if (!value || value.length > 128 || !/^[\w.-]+$/.test(value)) return;
+  return value;
+}

package/src/config/config.ts

@@ -0,0 +1,83 @@
+import type { VonaApplication } from 'vona';
+
+interface TelemetryEnv {
+  TELEMETRY_ENABLED?: string;
+  TELEMETRY_SERVICE_NAME?: string;
+  TELEMETRY_SAMPLING_ROOT_RATIO?: string;
+  TELEMETRY_OTLP_HTTP_URL?: string;
+  TELEMETRY_OTLP_HTTP_HEADERS?: string;
+  TELEMETRY_EXPORT_MAX_QUEUE_SIZE?: string;
+  TELEMETRY_EXPORT_DELAY_MS?: string;
+  TELEMETRY_EXPORT_TIMEOUT_MS?: string;
+  TELEMETRY_SHUTDOWN_TIMEOUT_MS?: string;
+  TELEMETRY_INGRESS_TRUSTED_PROXY_CIDRS?: string;
+  TELEMETRY_INGRESS_INTERNAL_HEADER?: string;
+  TELEMETRY_INGRESS_INTERNAL_HEADER_VALUE?: string;
+}
+
+export interface ITelemetryIngressConfig {
+  trustedProxyCidrs: string[];
+  internalHeader: string;
+  internalHeaderValue: string;
+}
+
+export interface ITelemetryConfig {
+  enabled: boolean;
+  serviceName: string;
+  requestIdHeader: string;
+  ingress: ITelemetryIngressConfig;
+  sampling: { rootRatio: number };
+  exporter: {
+    url: string;
+    headers?: Record<string, string>;
+    maxQueueSize: number;
+    scheduledDelayMillis: number;
+    exportTimeoutMillis: number;
+  };
+  shutdown: { timeoutMillis: number };
+}
+
+export function config(app: VonaApplication): ITelemetryConfig {
+  const env = app.meta.env as TelemetryEnv;
+  return {
+    enabled: env.TELEMETRY_ENABLED === 'true',
+    serviceName: env.TELEMETRY_SERVICE_NAME || app.name,
+    requestIdHeader: 'x-request-id',
+    ingress: {
+      trustedProxyCidrs: parseList(env.TELEMETRY_INGRESS_TRUSTED_PROXY_CIDRS),
+      internalHeader: env.TELEMETRY_INGRESS_INTERNAL_HEADER || 'x-vona-telemetry-ingress',
+      internalHeaderValue: env.TELEMETRY_INGRESS_INTERNAL_HEADER_VALUE || 'internal',
+    },
+    sampling: {
+      rootRatio: Number.parseFloat(env.TELEMETRY_SAMPLING_ROOT_RATIO || '0.1'),
+    },
+    exporter: {
+      url: env.TELEMETRY_OTLP_HTTP_URL || 'http://127.0.0.1:4318/v1/traces',
+      headers: parseHeaders(env.TELEMETRY_OTLP_HTTP_HEADERS),
+      maxQueueSize: Number.parseInt(env.TELEMETRY_EXPORT_MAX_QUEUE_SIZE || '2048'),
+      scheduledDelayMillis: Number.parseInt(env.TELEMETRY_EXPORT_DELAY_MS || '5000'),
+      exportTimeoutMillis: Number.parseInt(env.TELEMETRY_EXPORT_TIMEOUT_MS || '30000'),
+    },
+    shutdown: {
+      timeoutMillis: Number.parseInt(env.TELEMETRY_SHUTDOWN_TIMEOUT_MS || '5000'),
+    },
+  };
+}
+
+function parseList(value?: string) {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map(item => item.trim())
+    .filter(Boolean);
+}
+
+function parseHeaders(value?: string) {
+  if (!value) return undefined;
+  return Object.fromEntries(
+    value
+      .split(',')
+      .map(item => item.trim().split('='))
+      .filter(([key, headerValue]) => key && headerValue),
+  );
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './.metadata/index.ts';
+export * from './types/index.ts';

package/src/lib/ingress.ts

@@ -0,0 +1,34 @@
+import IP from '@eggjs/ip';
+
+import type { ITelemetryIngressConfig } from '../config/config.ts';
+
+type AddressMatcher = (address: string) => boolean;
+
+export function createIngressTrustChecker(config: ITelemetryIngressConfig) {
+  const trustedProxyMatchers = config.trustedProxyCidrs
+    .map(createAddressMatcher)
+    .filter((matcher): matcher is AddressMatcher => Boolean(matcher));
+
+  return (peerAddress?: string, internalHeaderValue?: string) => {
+    if (internalHeaderValue !== config.internalHeaderValue) return false;
+    const address = normalizePeerAddress(peerAddress);
+    if (!address) return false;
+    return trustedProxyMatchers.some(matcher => matcher(address));
+  };
+}
+
+function createAddressMatcher(rule: string): AddressMatcher | undefined {
+  try {
+    if (IP.isV4Format(rule) || IP.isV6Format(rule)) {
+      return address => address === rule;
+    }
+    return IP.cidrSubnet(rule).contains;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizePeerAddress(value?: string) {
+  if (!value) return;
+  return value.startsWith('::ffff:') ? value.slice('::ffff:'.length) : value;
+}

package/src/monkey.ts

@@ -0,0 +1,22 @@
+import type { IMonkeyAppClose, IMonkeyAppClosed, IMonkeyAppStart } from 'vona';
+
+import { BeanSimple } from 'vona';
+
+import { __ThisModule__ } from './.metadata/this.ts';
+
+export class Monkey
+  extends BeanSimple
+  implements IMonkeyAppStart, IMonkeyAppClose, IMonkeyAppClosed
+{
+  async appStart() {
+    this.app.scope(__ThisModule__).service.telemetry.init();
+  }
+
+  async appClose() {
+    await this.app.scope(__ThisModule__).service.telemetry.close(true);
+  }
+
+  async appClosed() {
+    await this.app.scope(__ThisModule__).service.telemetry.close(false);
+  }
+}