@blueking/open-telemetry 0.0.26 → 0.0.27

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/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 {};