@blueking/open-telemetry 0.0.26 → 0.0.28

package/dist/core/config.d.ts

@@ -71,8 +71,9 @@ export interface BkOTRequestConfig {
     allowedTracingUrls?: BkOTUrlMatcher | BkOTUrlMatcher[];
     excludedUrls?: BkOTUrlMatcher | BkOTUrlMatcher[];
     beforeSend?: (event: BkOTRequestEvent, context: BkOTRequestContext) => boolean | void;
+    /** 返回请求 URL 的低基数模板，例如 `/api/orders/{id}`；返回空值时回退到默认折叠规则。 */
+    getUrlTemplate?: (url: string) => string | undefined;
 }
-export type BkOTRequestOutcome = RumRequestOutcome;
 export type BkOTRequestContext = {
     error?: unknown;
     request: Request | RequestInit;
@@ -92,6 +93,7 @@ export interface BkOTRequestEvent {
         url?: string;
     };
 }
+export type BkOTRequestOutcome = RumRequestOutcome;
 export type BkOTSpanProcessorMode = 'batch' | 'simple';
 export interface BkOTTrackingConfig {
     action?: BkOTActionPluginOptions | boolean;
@@ -124,8 +126,8 @@ export interface BkOTViewConfig {
     /** 自动计算初始加载与 SPA 路由的页面稳定耗时，默认开启。 */
     loadingTime?: boolean;
     tracking?: 'auto' | 'manual';
-    /** 返回低基数路由分组，例如 `/trace/:id`。 */
-    getPathGroup?: (url: string) => string | undefined;
+    /** 返回页面路由的低基数模板，例如 `/trace/:id`；返回空值时回退到默认折叠规则。 */
+    getUrlTemplate?: (url: string) => string | undefined;
 }
 export interface ResolvedApplicationConfig {
     environment: string;
@@ -154,7 +156,8 @@ export interface ResolvedConfigHooks {
     getCustomAttributes: () => Attributes;
     getErrorAttributes: () => Attributes;
     getPageAttributes: () => Attributes;
-    getViewPathGroup: (url: string) => string;
+    getRequestUrlTemplate: (url: string) => string;
+    getViewUrlTemplate: (url: string) => string;
     redactAttributes: (attributes: Attributes) => Attributes;
     redactUrl: (url: string) => string;
 }

package/dist/core/plugin.d.ts

@@ -1,7 +1,7 @@
 import type { BkOTActivityEvent } from './action-activity';
 import type { ResolvedBkOTConfig } from './config';
 import type { BkOTSessionLifecycleEvent, BkOTUserContext, BkOTViewCommand, BkOTViewContext } from './runtime-context';
-import type { Attributes, Span, SpanKind, TimeInput, Tracer } from '@opentelemetry/api';
+import type { Attributes, Link, Span, SpanKind, TimeInput, Tracer } from '@opentelemetry/api';
 import type { Instrumentation } from '@opentelemetry/instrumentation';
 export interface BkOTPlugin {
     enabled?: ((config: ResolvedBkOTConfig) => boolean) | boolean;
@@ -49,6 +49,8 @@ export interface BkOTStartSpanOptions {
     /** 用于从历史中解析 Session/View/Action 归属；默认复用数字类型 startTime。 */
     contextTime?: number;
     kind?: SpanKind;
+    /** 关联其他 trace 的 Span Link；OTel 要求在创建时传入。 */
+    links?: Link[];
     startTime?: TimeInput;
 }
 export declare const isPluginEnabled: (plugin: BkOTPlugin, config: ResolvedBkOTConfig) => boolean;

package/dist/core/runtime-context.d.ts

@@ -37,7 +37,7 @@ export interface BkOTViewContext {
     name?: string;
     startedAt?: number;
     url?: string;
-    urlPathGroup?: string;
+    urlTemplate?: string;
 }
 /**
  * 管理 SDK 运行期公共属性快照。

package/dist/core/trace-context.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 被观测请求的 Trace Context 规划。
+ *
+ * 后端 APM 只解析 W3C `traceparent`，并且要求一个后端 trace 只对应一个 API 请求，因此这里不复用
+ * RUM Span 自身的 trace context，而是为每个命中白名单的请求生成独立的 trace-id/span-id，再通过
+ * Span Link 把后端 trace 关联回 RUM Span。
+ *
+ * 如果业务已经自行设置了 trace header（`traceparent`、`sentry-trace`、b3、Datadog、sw8），则完全
+ * 不注入，避免破坏业务既有的传播方式，只把已有链路建成 Link。
+ *
+ * Link 结构恒定：`context` 承载 trace-id/span-id，`attributes` 记录命中的格式与原始 header。
+ * sw8 这类无法映射为合法 OTel id 的格式会补一对占位 id，让 Link 结构保持统一。
+ */
+import type { Attributes, Link } from '@opentelemetry/api';
+/** 大小写不敏感地读取一个请求 header */
+export type BkOTHeaderReader = (name: string) => string | undefined;
+export interface BkOTRequestTracePlan {
+    /** 关联后端 trace 的 Span Link，恒为一条 */
+    links: Link[];
+    /** 需要注入的 traceparent；业务已有 trace header 时为 undefined */
+    traceparent?: string;
+}
+export type BkOTUpstreamTraceFormat = 'b3' | 'b3-multi' | 'datadog' | 'sentry-trace' | 'sw8' | 'traceparent';
+export declare const TRACEPARENT_HEADER = "traceparent";
+interface UpstreamTrace {
+    format: BkOTUpstreamTraceFormat;
+    /** 命中格式的原始 header，原样写入 Link Attributes */
+    headers: Attributes;
+    sampled?: boolean;
+    /** 规范化后的合法 OTel id；无法映射时两者同时缺失 */
+    spanId?: string;
+    traceId?: string;
+}
+export declare const detectUpstreamTrace: (getHeader: BkOTHeaderReader) => UpstreamTrace | undefined;
+export declare const planRequestTrace: (getHeader: BkOTHeaderReader) => BkOTRequestTracePlan;
+export {};

package/dist/core/url.d.ts

@@ -1,5 +1,10 @@
 import type { BkOTUrlMatcher, ResolvedBkOTConfig } from './config';
 export declare const toAbsoluteUrl: (url: string) => string;
+/**
+ * 常见数字 ID、UUID 和长十六进制段统一折叠为 :id，便于服务端按路由聚合。
+ * 同时服务 `view.url_template`（页面路由）与 `url.template`（请求路径）两个维度。
+ */
+export declare const normalizeUrlPathTemplate: (pathGroup: string) => string;
 export declare const isBkOTEndpoint: (config: ResolvedBkOTConfig, url: string) => boolean;
 export declare const shouldIgnoreUrl: (config: ResolvedBkOTConfig, url: string) => boolean;
 export declare const matchesUrlList: (matchers: BkOTUrlMatcher | BkOTUrlMatcher[] | undefined, url: string) => boolean;