@apifuse/connector-sdk 2.0.0-beta.1

package/src/runtime/instrumentation.ts

@@ -0,0 +1,424 @@
+import type { ConnectorContext } from "../types";
+import {
+	type CreateTraceContextOptions,
+	createTraceContext,
+	getTraceRecorder,
+	type TraceContext,
+} from "./trace";
+
+export interface InstrumentationOptions extends CreateTraceContextOptions {}
+
+export type InstrumentedConnectorContext<T extends ConnectorContext> = Omit<
+	T,
+	"trace"
+> & {
+	trace: TraceContext;
+};
+
+type InstrumentedNamespace = "http" | "tls" | "browser" | "session" | "state";
+
+const BROWSER_PAGE_METHODS = new Set([
+	"goto",
+	"fill",
+	"click",
+	"type",
+	"waitForSelector",
+]);
+
+function getErrorStatus(error: unknown): number | undefined {
+	if (
+		typeof error === "object" &&
+		error !== null &&
+		"status" in error &&
+		typeof error.status === "number"
+	) {
+		return error.status;
+	}
+
+	return undefined;
+}
+
+function getResponseDuration(result: unknown): number | undefined {
+	if (
+		typeof result === "object" &&
+		result !== null &&
+		"meta" in result &&
+		typeof result.meta === "object" &&
+		result.meta !== null &&
+		"duration" in result.meta &&
+		typeof result.meta.duration === "number"
+	) {
+		return result.meta.duration;
+	}
+
+	return undefined;
+}
+
+function getResponseStatus(
+	namespace: InstrumentedNamespace,
+	result: unknown,
+): number | undefined {
+	if (
+		typeof result === "object" &&
+		result !== null &&
+		"status" in result &&
+		typeof result.status === "number"
+	) {
+		return result.status;
+	}
+
+	if (namespace === "http") {
+		return 200;
+	}
+
+	return undefined;
+}
+
+function getUrl(
+	namespace: InstrumentedNamespace,
+	args: unknown[],
+	result?: unknown,
+): string | undefined {
+	if (typeof args[0] === "string") {
+		return args[0];
+	}
+
+	if (
+		namespace === "browser" &&
+		typeof result === "object" &&
+		result !== null &&
+		"url" in result &&
+		typeof result.url === "string"
+	) {
+		return result.url;
+	}
+
+	return undefined;
+}
+
+function getMethod(
+	namespace: InstrumentedNamespace,
+	methodName: string,
+	args: unknown[],
+): string | undefined {
+	if (namespace === "http") {
+		return methodName.toUpperCase();
+	}
+
+	if (namespace === "tls") {
+		const options =
+			typeof args[1] === "object" && args[1] !== null ? args[1] : undefined;
+		if (options && "method" in options && typeof options.method === "string") {
+			return options.method.toUpperCase();
+		}
+
+		return "GET";
+	}
+
+	return undefined;
+}
+
+function buildSpanAttributes(
+	namespace: InstrumentedNamespace,
+	methodName: string,
+	args: unknown[],
+	result?: unknown,
+	error?: unknown,
+): Record<string, string | number | boolean> {
+	const attributes: Record<string, string | number | boolean> = {};
+	const url = getUrl(namespace, args, result);
+	const method = getMethod(namespace, methodName, args);
+	const status = error
+		? getErrorStatus(error)
+		: getResponseStatus(namespace, result);
+	const duration = error ? undefined : getResponseDuration(result);
+
+	if (url) {
+		attributes.url = url;
+	}
+
+	if (method) {
+		attributes.method = method;
+	}
+
+	if (status !== undefined && (namespace === "http" || namespace === "tls")) {
+		attributes.status = status;
+	}
+
+	if (duration !== undefined) {
+		attributes.duration_ms = duration;
+	}
+
+	if (namespace === "session" || namespace === "state") {
+		attributes.operation = methodName;
+		const key = typeof args[0] === "string" ? args[0] : undefined;
+		if (key) {
+			attributes.key = key;
+		}
+	}
+
+	return attributes;
+}
+
+function getBrowserPageAttributes(
+	methodName: string,
+	args: unknown[],
+	elapsedMs?: number,
+	error?: unknown,
+): Record<string, string | number | boolean> {
+	const attributes: Record<string, string | number | boolean> = {};
+
+	if (methodName === "goto") {
+		const url = typeof args[0] === "string" ? args[0] : undefined;
+		if (url) {
+			attributes.url = url;
+		}
+		if (error === undefined) {
+			attributes.navigation_ms = elapsedMs ?? 0;
+		}
+		return attributes;
+	}
+
+	const selector = typeof args[0] === "string" ? args[0] : undefined;
+	if (selector) {
+		attributes.selector = selector;
+	}
+
+	if (error === undefined) {
+		const key = methodName === "waitForSelector" ? "wait_ms" : "action_ms";
+		attributes[key] = elapsedMs ?? 0;
+	}
+
+	return attributes;
+}
+
+function wrapPage<T extends object>(page: T, trace: TraceContext): T {
+	if (page === null || page === undefined) {
+		return page;
+	}
+
+	const recorder = getTraceRecorder(trace);
+	if (!recorder) {
+		return page;
+	}
+
+	const wrappedMethods = new Map<PropertyKey, unknown>();
+
+	return new Proxy(page, {
+		get(pageTarget, property, receiver) {
+			const value = Reflect.get(pageTarget, property, receiver);
+
+			if (
+				typeof value !== "function" ||
+				property === "constructor" ||
+				!BROWSER_PAGE_METHODS.has(String(property))
+			) {
+				return value;
+			}
+
+			if (wrappedMethods.has(property)) {
+				return wrappedMethods.get(property);
+			}
+
+			const methodName = String(property);
+			const wrapped = (...args: unknown[]) => {
+				let elapsedMs = 0;
+
+				return recorder.runSpan(
+					`browser.page.${methodName}`,
+					async () => {
+						const startedAt = Date.now();
+						const result = await Reflect.apply(value, pageTarget, args);
+						elapsedMs = Date.now() - startedAt;
+						return result;
+					},
+					{
+						onSuccess: () =>
+							getBrowserPageAttributes(methodName, args, elapsedMs),
+						onError: (error) =>
+							getBrowserPageAttributes(methodName, args, undefined, error),
+					},
+				);
+			};
+
+			wrappedMethods.set(property, wrapped);
+			return wrapped;
+		},
+	});
+}
+
+function wrapNamespace<T extends object>(
+	namespace: InstrumentedNamespace,
+	target: T,
+	trace: TraceContext,
+): T {
+	const recorder = getTraceRecorder(trace);
+	if (!recorder) {
+		return target;
+	}
+
+	const wrappedMethods = new Map<PropertyKey, unknown>();
+
+	return new Proxy(target, {
+		get(namespaceTarget, property, receiver) {
+			const value = Reflect.get(namespaceTarget, property, receiver);
+
+			if (typeof value !== "function" || property === "constructor") {
+				return value;
+			}
+
+			if (namespace === "browser" && property === "newPage") {
+				if (wrappedMethods.has(property)) {
+					return wrappedMethods.get(property);
+				}
+
+				const wrapped = (...args: unknown[]) => {
+					let allocateMs = 0;
+
+					return recorder.runSpan(
+						"browser.newPage",
+						async () => {
+							const startedAt = Date.now();
+							const page = await Reflect.apply(value, namespaceTarget, args);
+							allocateMs = Date.now() - startedAt;
+							return wrapPage(page, trace);
+						},
+						{
+							onSuccess: (result) => {
+								const attributes: Record<string, string | number | boolean> = {
+									allocate_ms: allocateMs,
+								};
+
+								if (
+									result &&
+									typeof result === "object" &&
+									"pageId" in result &&
+									typeof (result as { pageId?: unknown }).pageId === "string"
+								) {
+									attributes.page_id = (result as { pageId: string }).pageId;
+								}
+
+								if (
+									namespaceTarget &&
+									typeof namespaceTarget === "object" &&
+									"engine" in namespaceTarget &&
+									typeof (namespaceTarget as { engine?: unknown }).engine ===
+										"string"
+								) {
+									attributes.engine = (
+										namespaceTarget as { engine: string }
+									).engine;
+								}
+
+								return attributes;
+							},
+							onError: (error) =>
+								getBrowserPageAttributes("newPage", args, undefined, error),
+						},
+					);
+				};
+
+				wrappedMethods.set(property, wrapped);
+				return wrapped;
+			}
+
+			if (wrappedMethods.has(property)) {
+				return wrappedMethods.get(property);
+			}
+
+			const methodName = String(property);
+			if (namespace === "browser") {
+				const wrapped = (...args: unknown[]) => {
+					let elapsedMs = 0;
+
+					return recorder.runSpan(
+						`browser.${methodName}`,
+						async () => {
+							const startedAt = Date.now();
+							const result = await Reflect.apply(value, namespaceTarget, args);
+							elapsedMs = Date.now() - startedAt;
+							return result;
+						},
+						{
+							onSuccess: () =>
+								getBrowserPageAttributes(methodName, args, elapsedMs),
+							onError: (error) =>
+								getBrowserPageAttributes(methodName, args, undefined, error),
+						},
+					);
+				};
+
+				wrappedMethods.set(property, wrapped);
+				return wrapped;
+			}
+
+			const wrapped = (...args: unknown[]) =>
+				recorder.runSpan(
+					`${namespace}.${methodName}`,
+					() => Reflect.apply(value, namespaceTarget, args),
+					{
+						onSuccess: (result) =>
+							buildSpanAttributes(namespace, methodName, args, result),
+						onError: (error) =>
+							buildSpanAttributes(
+								namespace,
+								methodName,
+								args,
+								undefined,
+								error,
+							),
+					},
+				);
+
+			wrappedMethods.set(property, wrapped);
+			return wrapped;
+		},
+	});
+}
+
+function hasTraceOverrides(options: InstrumentationOptions): boolean {
+	return options.maxSpans !== undefined || options.onSpan !== undefined;
+}
+
+export function wrapWithInstrumentation<T extends ConnectorContext>(
+	ctx: T,
+	options: InstrumentationOptions = {},
+): InstrumentedConnectorContext<T> {
+	const trace =
+		getTraceRecorder(ctx.trace) && !hasTraceOverrides(options)
+			? (ctx.trace as TraceContext)
+			: createTraceContext(options);
+	const wrappedTargets = new Map<InstrumentedNamespace, unknown>();
+
+	return new Proxy(ctx, {
+		get(target, property, receiver) {
+			if (property === "trace") {
+				return trace;
+			}
+
+			if (
+				property === "http" ||
+				property === "tls" ||
+				property === "browser" ||
+				property === "session" ||
+				property === "state"
+			) {
+				const namespace = property;
+				if (wrappedTargets.has(namespace)) {
+					return wrappedTargets.get(namespace);
+				}
+
+				const value = Reflect.get(target, property, receiver);
+				if (!value || typeof value !== "object") {
+					return value;
+				}
+
+				const wrapped = wrapNamespace(namespace, value, trace);
+				wrappedTargets.set(namespace, wrapped);
+				return wrapped;
+			}
+
+			return Reflect.get(target, property, receiver);
+		},
+	}) as unknown as InstrumentedConnectorContext<T>;
+}

package/src/runtime/otlp.ts

@@ -0,0 +1,171 @@
+import type { TraceSpan } from "../types";
+
+export interface OTLPExportOptions {
+	endpoint: string;
+	headers?: Record<string, string>;
+	timeout?: number;
+}
+
+let nextTraceId = 1n;
+let replayableTraceId: { signature: string; traceId: string } | null = null;
+
+function createBatchSignature(
+	spans: TraceSpan[],
+	resourceAttributes?: Record<string, string>,
+): string {
+	return JSON.stringify({
+		resourceAttributes: resourceAttributes ?? null,
+		spans,
+	});
+}
+
+function createTraceId(signature: string): string {
+	if (replayableTraceId?.signature === signature) {
+		const traceId = replayableTraceId.traceId;
+		replayableTraceId = null;
+		return traceId;
+	}
+
+	const traceId = nextTraceId.toString(16).padStart(32, "0");
+	nextTraceId += 1n;
+	replayableTraceId = { signature, traceId };
+	return traceId;
+}
+
+function normalizeHexId(
+	value: string | undefined,
+	length: number,
+): string | undefined {
+	if (!value) {
+		return undefined;
+	}
+
+	const normalized = value.replace(/[^a-fA-F0-9]/g, "").toLowerCase();
+	return normalized.padStart(length, "0").slice(-length);
+}
+
+function toAttributeValue(
+	value: unknown,
+): Record<string, string | number | boolean> {
+	if (typeof value === "string") {
+		return { stringValue: value };
+	}
+
+	if (typeof value === "number") {
+		return { doubleValue: value };
+	}
+
+	if (typeof value === "boolean") {
+		return { boolValue: value };
+	}
+
+	return { stringValue: String(value) };
+}
+
+export function spansToOTLP(
+	spans: TraceSpan[],
+	resourceAttributes?: Record<string, string>,
+): {
+	resourceSpans: Array<{
+		resource: {
+			attributes: Array<{
+				key: string;
+				value: Record<string, string>;
+			}>;
+		};
+		scopeSpans: Array<{
+			scope: { name: string; version: string };
+			spans: Array<{
+				attributes: Array<{
+					key: string;
+					value: Record<string, string | number | boolean>;
+				}>;
+				endTimeUnixNano: string;
+				kind: number;
+				name: string;
+				parentSpanId?: string;
+				spanId: string;
+				startTimeUnixNano: string;
+				status: { code: number };
+				traceId: string;
+			}>;
+		}>;
+	}>;
+} {
+	const traceId = createTraceId(
+		createBatchSignature(spans, resourceAttributes),
+	);
+
+	return {
+		resourceSpans: [
+			{
+				resource: {
+					attributes: Object.entries(resourceAttributes ?? {}).map(
+						([key, value]) => ({
+							key,
+							value: { stringValue: value },
+						}),
+					),
+				},
+				scopeSpans: [
+					{
+						scope: {
+							name: "apifuse-connector-sdk",
+							version: "0.1.0",
+						},
+						spans: spans.map((span) => ({
+							traceId,
+							spanId: normalizeHexId(span.id, 16) ?? "0000000000000001",
+							parentSpanId: normalizeHexId(span.parentId, 16),
+							name: span.name,
+							kind: 2,
+							startTimeUnixNano: String(span.startedAt * 1_000_000),
+							endTimeUnixNano: String(span.endedAt * 1_000_000),
+							status: { code: span.status === "ok" ? 1 : 2 },
+							attributes: Object.entries(span.attributes ?? {}).map(
+								([key, value]) => ({
+									key,
+									value: toAttributeValue(value),
+								}),
+							),
+						})),
+					},
+				],
+			},
+		],
+	};
+}
+
+export async function exportSpansOTLP(
+	spans: TraceSpan[],
+	options: OTLPExportOptions,
+	resourceAttributes?: Record<string, string>,
+): Promise<void> {
+	if (spans.length === 0) {
+		return;
+	}
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), options.timeout ?? 5_000);
+
+	try {
+		const response = await fetch(options.endpoint, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...options.headers,
+			},
+			body: JSON.stringify(spansToOTLP(spans, resourceAttributes)),
+			signal: controller.signal,
+		});
+
+		if (!response.ok) {
+			throw new Error(`HTTP ${response.status}`);
+		}
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn("[apifuse] OTLP export failed:", message);
+	} finally {
+		clearTimeout(timer);
+	}
+}

package/src/runtime/perf.ts

@@ -0,0 +1,73 @@
+import type { Span } from "./trace";
+
+export type PerfStats = {
+	p50: number;
+	p95: number;
+	p99: number;
+	avg: number;
+	min: number;
+	max: number;
+};
+
+export function computePercentile(sortedValues: number[], p: number): number {
+	if (sortedValues.length === 0) {
+		return 0;
+	}
+
+	if (sortedValues.length === 1) {
+		return sortedValues[0] ?? 0;
+	}
+
+	const percentile = Math.min(100, Math.max(0, p));
+	const position = (percentile / 100) * (sortedValues.length - 1);
+	const lowerIndex = Math.floor(position);
+	const upperIndex = Math.ceil(position);
+	const lower = sortedValues[lowerIndex] ?? 0;
+	const upper = sortedValues[upperIndex] ?? lower;
+
+	if (lowerIndex === upperIndex) {
+		return lower;
+	}
+
+	const weight = position - lowerIndex;
+	return lower + (upper - lower) * weight;
+}
+
+export function computeStats(durations: number[]): PerfStats {
+	if (durations.length === 0) {
+		return {
+			p50: 0,
+			p95: 0,
+			p99: 0,
+			avg: 0,
+			min: 0,
+			max: 0,
+		};
+	}
+
+	const sorted = [...durations].sort((a, b) => a - b);
+	const total = sorted.reduce((sum, value) => sum + value, 0);
+
+	return {
+		p50: computePercentile(sorted, 50),
+		p95: computePercentile(sorted, 95),
+		p99: computePercentile(sorted, 99),
+		avg: total / sorted.length,
+		min: sorted[0] ?? 0,
+		max: sorted[sorted.length - 1] ?? 0,
+	};
+}
+
+export function groupSpansByName(allSpans: Span[][]): Map<string, number[]> {
+	const grouped = new Map<string, number[]>();
+
+	for (const spans of allSpans) {
+		for (const span of spans) {
+			const durations = grouped.get(span.name) ?? [];
+			durations.push(span.duration_ms);
+			grouped.set(span.name, durations);
+		}
+	}
+
+	return grouped;
+}