@blueking/open-telemetry 0.0.5 → 0.0.6

package/dist/core/config.d.ts

@@ -31,6 +31,7 @@ export interface BkOTConfig {
     sampleRate?: number;
     signalEndpoints?: SignalEndpointsConfig;
     spanBatch?: BkOTBatchConfig;
+    spanProcessor?: BkOTSpanProcessorMode;
     token?: string;
     traces?: SignalExporterInputConfig;
 }
@@ -89,10 +90,12 @@ export interface BkOTRumConfig extends BkOTInstrumentationsConfig {
     } | boolean;
     session?: {
         inactivityMs?: number;
+        maxLifetimeMs?: number;
         storageKey?: string;
     } | boolean;
 }
-export interface NormalizedBkOTConfig extends Omit<BkOTConfig, 'attributes' | 'autoStart' | 'debug' | 'enabled' | 'endpoint' | 'environment' | 'instrumentations' | 'logs' | 'metrics' | 'plugins' | 'redact' | 'signalEndpoints' | 'token' | 'traces'> {
+export type BkOTSpanProcessorMode = 'batch' | 'simple';
+export interface NormalizedBkOTConfig extends Omit<BkOTConfig, 'attributes' | 'autoStart' | 'debug' | 'enabled' | 'endpoint' | 'environment' | 'instrumentations' | 'logs' | 'metrics' | 'plugins' | 'redact' | 'signalEndpoints' | 'spanProcessor' | 'token' | 'traces'> {
     autoStart: boolean;
     debug: boolean;
     enabled: boolean;
@@ -105,6 +108,7 @@ export interface NormalizedBkOTConfig extends Omit<BkOTConfig, 'attributes' | 'a
     plugins: BkOTPlugin[];
     resourceAttributes: Attributes;
     sampleRate: number;
+    spanProcessor: BkOTSpanProcessorMode;
     traces: SignalExporterConfig;
     getCustomAttributes: () => Attributes;
     getErrorAttributes: () => Attributes;

package/dist/core/id.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 生成随机 ID。优先用 `crypto.randomUUID`（standards-compliant UUID v4），不可用时回退到
+ * `${prefix}-${timestamp}-${rand}` 形式。
+ *
+ * 注意：fallback 实现使用 Math.random，**不是密码学安全**，仅适用于设备/会话/事件标识等场景，
+ * 不要复用此函数生成 token、CSRF 防护等安全相关的值。
+ */
+export declare const createRandomId: (prefix: string) => string;

package/dist/core/plugin.d.ts

@@ -1,5 +1,5 @@
 import type { NormalizedBkOTConfig } from './config';
-import type { Attributes, Meter, Span, Tracer } from '@opentelemetry/api';
+import type { Attributes, Meter, Span, TimeInput, Tracer } from '@opentelemetry/api';
 import type { Logger, LogRecord } from '@opentelemetry/api-logs';
 export interface BkOTPlugin {
     enabled?: ((config: NormalizedBkOTConfig) => boolean) | boolean;
@@ -19,7 +19,20 @@ export interface BkOTRuntimeContext {
     emitLog: (record: LogRecord) => void;
     getRuntimeAttributes: () => Attributes;
     setRuntimeAttributes: (attributes: Attributes) => void;
-    startSpan: (name: string, attributes?: Attributes) => Span;
+    startSpan: (name: string, attributes?: Attributes, options?: BkOTStartSpanOptions) => Span;
+}
+/**
+ * startSpan 的扩展选项。
+ *
+ * 用于"事件实际发生在过去某个时刻，但 span 现在才创建"的场景：
+ * 例如 route-timing 在 raf+setTimeout 链路结束后才上报，但希望 span 的时间窗
+ * 反映真实的"路由切换瞬间到渲染完成"区间，方便 trace 视图与并发请求对齐。
+ *
+ * startTime 接受 OT TimeInput；常用 epoch 毫秒（performance.timeOrigin + performance.now()）。
+ * 配合 span.end(endTime?) 可控制结束时间。
+ */
+export interface BkOTStartSpanOptions {
+    startTime?: TimeInput;
 }
 export declare const isPluginEnabled: (plugin: BkOTPlugin, config: NormalizedBkOTConfig) => boolean;
 export declare const createPlugin: (plugin: BkOTPlugin) => BkOTPlugin;

package/dist/core/sdk.d.ts

@@ -1,7 +1,7 @@
 import { type Attributes, type Span } from '@opentelemetry/api';
 import { type Instrumentation } from '@opentelemetry/instrumentation';
 import { type BkOTConfig, type BkOTCustomEventPayload, type NormalizedBkOTConfig } from './config';
-import { type BkOTPlugin, type BkOTRuntimeContext } from './plugin';
+import { type BkOTPlugin, type BkOTRuntimeContext, type BkOTStartSpanOptions } from './plugin';
 import type { LogRecord } from '@opentelemetry/api-logs';
 export interface BkOTInstance extends BkOTRuntimeContext {
     flush: () => Promise<void>;
@@ -36,7 +36,7 @@ export declare class BkOpenTelemetry implements BkOTInstance {
     readonly setRuntimeAttributes: (attributes: Attributes) => void;
     readonly shutdown: () => Promise<void>;
     readonly start: () => Promise<void>;
-    readonly startSpan: (name: string, attributes?: Attributes) => Span;
+    readonly startSpan: (name: string, attributes?: Attributes, options?: BkOTStartSpanOptions) => Span;
     readonly tracer: BkOTRuntimeContext['tracer'];
     readonly use: (plugin: BkOTPlugin) => this;
     readonly useInstrumentation: (instrumentation: Instrumentation) => this;

package/dist/core/throttle.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 简易 djb2 字符串 hash。结果稳定、短（base36），足以区分常见 fingerprint 字符串组合。
+ * 不是密码学安全 hash，仅用于事件聚合分组场景。
+ */
+export declare const hashString: (input: string) => string;
+export interface ThrottleResult {
+    /** 是否允许本次上报 */
+    allowed: boolean;
+    /** 当前窗口内同 fingerprint 的总触发次数（含本次，含被丢弃次数），便于下游感知是否被节流 */
+    count: number;
+}
+/**
+ * 时间窗节流：同一 key 在 windowMs 窗口内最多允许 maxPerWindow 次通过；
+ * 超出则被拦截，但 `count` 仍累加，便于下游感知风暴规模。
+ *
+ * 长会话场景下避免 records 无限累积——按窗口长度节奏轻量清理一次过期 entry。
+ */
+export declare const createThrottle: (windowMs: number, maxPerWindow: number) => {
+    allow(key: string): ThrottleResult;
+};