@apifuse/provider-sdk 2.2.0-beta.39 → 2.2.0-beta.40

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # @apifuse/provider-sdk Changelog
 
+## 2.2.0-beta.40
+
+- Release candidate for main commit 7e2f05a954c23593a77e89e463a9bcbc2cdc7695.
+
 ## 2.2.0-beta.39
 
 - Release candidate for main commit ecbe349c44e15c873b7c58b42e14610db029eb5f.

package/dist/config/loader.d.ts

@@ -64,6 +64,8 @@ export type SmartproxyAllocatorBodyClass = "network_error" | "http_error" | "emp
 export type ProxyUserAgentSource = "declared" | "defaulted";
 export type ProxyResolutionTelemetryEvent = {
     provider: ProxyVendorName;
+    /** Defaults to `"ok"` when omitted. */
+    outcome?: "ok" | "error";
     userAgentSource?: ProxyUserAgentSource;
     protocol?: ProxyProtocol;
     cacheStatus: ProxyCacheStatus;

package/dist/config/loader.js

@@ -158,6 +158,7 @@ function telemetryForPool(pool, cacheStatus, startedAt, extra = {}) {
 function telemetryForFailure(cacheStatus, startedAt, extra = {}) {
     return {
         provider: "smartproxy",
+        outcome: "error",
         cacheStatus,
         cacheHit: false,
         resolutionMs: Math.max(0, Date.now() - startedAt),

package/dist/fixture-sanitization.d.ts

@@ -24,3 +24,5 @@ export declare function sanitizeUrlForLogs(value: string): string;
 export declare function requestPathForFixture(value: string): string;
 /** Scrubs secrets and terminal/log control characters before diagnostic text is emitted. */
 export declare function sanitizeDiagnosticText(value: string): string;
+/** Encodes terminal/log control characters without applying value-level secret heuristics. */
+export declare function encodeDiagnosticControls(value: string): string;

package/dist/fixture-sanitization.js

@@ -170,7 +170,8 @@ function isCredentialBearingUrl(value) {
         return false;
     }
 }
-function encodeDiagnosticControls(value) {
+/** Encodes terminal/log control characters without applying value-level secret heuristics. */
+export function encodeDiagnosticControls(value) {
     let result = "";
     for (const character of value) {
         const code = character.codePointAt(0) ?? 0;

package/dist/index.d.ts

@@ -31,7 +31,7 @@ export { generateInsights } from "./runtime/insights.js";
 export { type InstrumentationOptions, type InstrumentedProviderContext, wrapWithInstrumentation, } from "./runtime/instrumentation.js";
 export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
-export type { ProxyTelemetryLogPayload } from "./runtime/proxy-telemetry.js";
+export type { ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "./runtime/proxy-telemetry.js";
 export { APIFUSE__CDP_POOL__URL, APIFUSE__RESOLVER__2CAPTCHA__API_KEY, APIFUSE__RESOLVER__CAPMONSTER__API_KEY, APIFUSE__RESOLVER__CAPSOLVER__API_KEY, APIFUSE__RESOLVER__TIMEOUT_MS, DEFAULT_RESOLVER_TIMEOUT_MS, } from "./runtime/resolver-config.js";
 export { createUnsupportedResolverClient } from "./runtime/resolver-shared.js";
 export type { ResolverRuntimeOptions } from "./runtime/resolver.js";

package/dist/runtime/proxy-telemetry.d.ts

@@ -1,6 +1,7 @@
 import type { ProxyAttemptTelemetryEvent, ProxyCacheStatus, ProxyProtocol, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyUserAgentSource, ProxyVendorFailoverTelemetryEvent, ProxyVendorName, SmartproxyAllocatorBodyClass } from "../config/loader.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
-export type ProxyTelemetryLogPayload = {
+export type ProxyTelemetryResolvedPayload = {
+    kind: "resolved";
     provider: ProxyVendorName;
     userAgentSource?: ProxyUserAgentSource;
     protocol?: ProxyProtocol;
@@ -39,6 +40,43 @@ export type ProxyTelemetryLogPayload = {
         a?: number;
     }[];
 };
+export type ProxyTelemetryUnresolvedPayload = {
+    kind: "unresolved";
+    /** Distinct vendors that failed resolution or recorded a failover, in order seen. */
+    vendors: ProxyVendorName[];
+    cacheStatus?: ProxyCacheStatus;
+    cacheHit?: boolean;
+    resolutionMs?: number;
+    allocatorMs?: number;
+    allocatorStatus?: number;
+    allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+    allocatorAttempts?: number;
+    lockWaitMs?: number;
+    redisReadMs?: number;
+    redisWriteMs?: number;
+    poolAgeMs?: number;
+    poolExpiresInMs?: number;
+    attempts?: number;
+    refreshes?: number;
+    failovers?: {
+        v: ProxyVendorName;
+        nx?: ProxyVendorName;
+        p: ProxyVendorFailoverTelemetryEvent["phase"];
+        r: ProxyVendorFailoverTelemetryEvent["reason"];
+        a?: number;
+    }[];
+    attemptSamples?: {
+        n: number;
+        a: number;
+        i?: number;
+        h?: string;
+        o: ProxyAttemptTelemetryEvent["outcome"];
+        c?: string;
+        s?: number;
+        d?: number;
+    }[];
+};
+export type ProxyTelemetryLogPayload = ProxyTelemetryResolvedPayload | ProxyTelemetryUnresolvedPayload;
 export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
     #private;
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;

package/dist/runtime/proxy-telemetry.js

@@ -30,9 +30,12 @@ export class ProxyTelemetryCollector {
     #events = [];
     #attempts = [];
     #failovers = [];
+    #unresolvedVendors = [];
     recordProxyResolution(event) {
+        const outcome = event.outcome === "error" ? "error" : "ok";
         this.#events.push({
             provider: event.provider,
+            outcome,
             ...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
             ...(event.protocol ? { protocol: event.protocol } : {}),
             cacheStatus: event.cacheStatus,
@@ -56,6 +59,9 @@ export class ProxyTelemetryCollector {
             attempts: Math.max(1, Math.floor(event.attempts || 1)),
             refreshes: event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
         });
+        if (outcome === "error" && !this.#unresolvedVendors.includes(event.provider)) {
+            this.#unresolvedVendors.push(event.provider);
+        }
     }
     recordProxyVendorFailover(event) {
         if (this.#failovers.length >= MAX_PROXY_FAILOVER_SAMPLES)
@@ -67,6 +73,9 @@ export class ProxyTelemetryCollector {
             reason: event.reason,
             ...(event.attempt === undefined ? {} : { attempt: Math.max(0, Math.floor(event.attempt)) }),
         });
+        if (!this.#unresolvedVendors.includes(event.vendor)) {
+            this.#unresolvedVendors.push(event.vendor);
+        }
     }
     recordProxyAttempt(event) {
         if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES)
@@ -88,11 +97,90 @@ export class ProxyTelemetryCollector {
     }
     toLogPayload() {
         const [first, ...rest] = this.#events;
-        if (!first)
-            return undefined;
-        // The serving vendor/protocol is the last recorded resolution (a failed
-        // vendor records first, the vendor that served records last).
-        const serving = this.#events[this.#events.length - 1] ?? first;
+        const okEvents = this.#events.filter((event) => event.outcome !== "error");
+        const attemptSamples = this.#attempts.map((attempt, index) => ({
+            n: index + 1,
+            a: attempt.attempt,
+            ...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
+            ...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
+            o: attempt.outcome,
+            ...(attempt.errorCode ? { c: attempt.errorCode } : {}),
+            ...(attempt.status === undefined ? {} : { s: attempt.status }),
+            ...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
+        }));
+        const failovers = this.#failovers.map((failover) => ({
+            v: failover.vendor,
+            ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+            p: failover.phase,
+            r: failover.reason,
+            ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
+        }));
+        if (okEvents.length === 0) {
+            if (!first && failovers.length === 0)
+                return undefined;
+            const failureEvents = this.#events.filter((event) => event.outcome === "error");
+            const [firstFailure, ...remainingFailures] = failureEvents;
+            const aggregate = firstFailure
+                ? remainingFailures.reduce((acc, event) => ({
+                    provider: event.provider,
+                    outcome: "error",
+                    cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
+                    cacheHit: acc.cacheHit && event.cacheHit,
+                    resolutionMs: acc.resolutionMs + event.resolutionMs,
+                    allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
+                    allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
+                    allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
+                    allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
+                    lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
+                    redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
+                    redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
+                    poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
+                    poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
+                    attempts: acc.attempts + event.attempts,
+                    refreshes: sumOptional(acc.refreshes, event.refreshes),
+                }), firstFailure)
+                : undefined;
+            return {
+                kind: "unresolved",
+                vendors: [...this.#unresolvedVendors],
+                ...(aggregate
+                    ? {
+                        cacheStatus: aggregate.cacheStatus,
+                        cacheHit: aggregate.cacheHit,
+                        resolutionMs: aggregate.resolutionMs,
+                        ...(aggregate.allocatorMs !== undefined
+                            ? { allocatorMs: aggregate.allocatorMs }
+                            : {}),
+                        ...(aggregate.allocatorStatus !== undefined
+                            ? { allocatorStatus: aggregate.allocatorStatus }
+                            : {}),
+                        ...(aggregate.allocatorBodyClass !== undefined
+                            ? { allocatorBodyClass: aggregate.allocatorBodyClass }
+                            : {}),
+                        ...(aggregate.allocatorAttempts !== undefined
+                            ? { allocatorAttempts: aggregate.allocatorAttempts }
+                            : {}),
+                        ...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
+                        ...(aggregate.redisReadMs !== undefined
+                            ? { redisReadMs: aggregate.redisReadMs }
+                            : {}),
+                        ...(aggregate.redisWriteMs !== undefined
+                            ? { redisWriteMs: aggregate.redisWriteMs }
+                            : {}),
+                        ...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
+                        ...(aggregate.poolExpiresInMs !== undefined
+                            ? { poolExpiresInMs: aggregate.poolExpiresInMs }
+                            : {}),
+                        attempts: aggregate.attempts,
+                        ...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
+                    }
+                    : {}),
+                ...(failovers.length > 0 ? { failovers } : {}),
+                ...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+            };
+        }
+        // The serving vendor/protocol is the last successful resolution.
+        const serving = okEvents[okEvents.length - 1] ?? first;
         const vendors = [];
         for (const event of this.#events) {
             if (!vendors.includes(event.provider))
@@ -117,6 +205,7 @@ export class ProxyTelemetryCollector {
             refreshes: sumOptional(acc.refreshes, event.refreshes),
         }), first);
         return {
+            kind: "resolved",
             provider: serving.provider,
             ...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
             ...(serving.protocol ? { protocol: serving.protocol } : {}),
@@ -142,32 +231,9 @@ export class ProxyTelemetryCollector {
                 : {}),
             attempts: aggregate.attempts,
             ...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
-            ...(this.#attempts.length > 0
-                ? {
-                    attemptSamples: this.#attempts.map((attempt, index) => ({
-                        n: index + 1,
-                        a: attempt.attempt,
-                        ...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
-                        ...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
-                        o: attempt.outcome,
-                        ...(attempt.errorCode ? { c: attempt.errorCode } : {}),
-                        ...(attempt.status === undefined ? {} : { s: attempt.status }),
-                        ...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
-                    })),
-                }
-                : {}),
+            ...(attemptSamples.length > 0 ? { attemptSamples } : {}),
             ...(vendors.length > 1 ? { vendors } : {}),
-            ...(this.#failovers.length > 0
-                ? {
-                    failovers: this.#failovers.map((failover) => ({
-                        v: failover.vendor,
-                        ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
-                        p: failover.phase,
-                        r: failover.reason,
-                        ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
-                    })),
-                }
-                : {}),
+            ...(failovers.length > 0 ? { failovers } : {}),
         };
     }
     toHeaderValue() {

package/dist/runtime/trace-config.d.ts

@@ -0,0 +1,12 @@
+import type { TraceConfig } from "../types.js";
+/** SDK-owned environment variable names for server trace output. */
+export declare const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export declare const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+type EnvLike = Record<string, string | undefined>;
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export declare function resolveTraceConfigFromEnv(env?: EnvLike): TraceConfig | undefined;
+export {};

package/dist/runtime/trace-config.js

@@ -0,0 +1,61 @@
+/** SDK-owned environment variable names for server trace output. */
+export const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+const TRACE_EXPORTER_LOOKUP = {
+    console: true,
+    json: true,
+    none: true,
+};
+const TRACE_EXPORTERS = new Set(Object.keys(TRACE_EXPORTER_LOOKUP));
+const emittedWarnings = new Set();
+function warnOnce(key, message) {
+    if (emittedWarnings.has(key))
+        return;
+    emittedWarnings.add(key);
+    console.warn(message);
+}
+function parseEnabled(raw) {
+    if (raw === undefined)
+        return undefined;
+    switch (raw.trim().toLowerCase()) {
+        case "1":
+        case "true":
+        case "yes":
+        case "on":
+            return true;
+        case "0":
+        case "false":
+        case "no":
+        case "off":
+            return false;
+        default:
+            warnOnce(APIFUSE__TRACE__ENABLED, "[apifuse] Invalid APIFUSE__TRACE__ENABLED; falling back to disabled tracing.");
+            return false;
+    }
+}
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export function resolveTraceConfigFromEnv(env = process.env) {
+    const enabledRaw = env[APIFUSE__TRACE__ENABLED];
+    const exporterRaw = env[APIFUSE__TRACE__EXPORTER];
+    if (enabledRaw === undefined && exporterRaw === undefined) {
+        return undefined;
+    }
+    const enabled = parseEnabled(enabledRaw);
+    const normalizedExporter = exporterRaw?.trim().toLowerCase();
+    const exporter = TRACE_EXPORTERS.has(normalizedExporter)
+        ? normalizedExporter
+        : exporterRaw === undefined
+            ? undefined
+            : "none";
+    if (exporterRaw !== undefined && exporter === "none" && normalizedExporter !== "none") {
+        warnOnce(APIFUSE__TRACE__EXPORTER, `[apifuse] Invalid APIFUSE__TRACE__EXPORTER value "${normalizedExporter ?? exporterRaw}" (OTLP is unsupported for server output); supported exporters are "console", "json", and "none"; falling back to exporter "none".`);
+    }
+    return {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(exporter !== undefined ? { exporter } : {}),
+    };
+}

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 export type { ProxyCacheStatus, ProxyProtocol, ProxyUserAgentSource, ProxyVendorName, SmartproxyAllocatorBodyClass, } from "../config/loader.js";
-export type { ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
+export type { ProxyTelemetryLogPayload, ProxyTelemetryResolvedPayload, ProxyTelemetryUnresolvedPayload, } from "../runtime/proxy-telemetry.js";
 export { createServerApp, createServerAppAsync, ERROR_OBSERVABILITY_HEADER, type ErrorObservabilityDetails, type ProviderServerCloseOptions, type ProviderServerHandle, type ProviderServerLogEvent, type ProviderServerLogger, type ProviderServerOperationExecutor, type ProviderServerOperationExecutorInput, type ProviderServerOptions, type ProviderServerStatefulForwardEnvelope, type ServeOptions, serve, } from "./serve.js";
 export { computeSelfTestPlanDigest, createSelfTestApp, createSelfTestAuthFlowInvoke, createSelfTestInvoke, DEFAULT_SELF_TEST_REQUEST_BUDGET_MS, isSelfTestReadOnlyOperation, PROVIDER_RUNTIME_SELF_TEST_REQUEST_BUDGET_MS_ENV, resolveSelfTestPort, SELF_TEST_AUTH_FLOW_MULTI_TURN_SKIP_REASON, SELF_TEST_AUTH_FLOW_REJECTED_SKIP_REASON, SELF_TEST_HEALTHZ_PATH, SELF_TEST_PATH, SELF_TEST_SCHEMA_VERSION, type SelfTestAppOptions, type SelfTestAuthFlowInvoke, type SelfTestAuthFlowRoute, type SelfTestCaseResult, type SelfTestCaseStatus, type SelfTestOperationInvoke, type SelfTestRequest, SelfTestRequestSchema, type SelfTestResponse, } from "./self-test.js";
 export { type InputDateTokenCalendar, resolveHealthCheckInputDateTokens, } from "./self-test-input-tokens.js";

package/dist/server/serve-implementation.js

@@ -28,6 +28,7 @@ import { createProviderRuntimeStateFromEnv, createUnsupportedProviderRuntimeStat
 import { StealthCookieJar } from "../runtime/stealth-cookies.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
 import { createTraceContext } from "../runtime/trace.js";
+import { resolveTraceConfigFromEnv } from "../runtime/trace-config.js";
 import { parseSchema } from "../schema.js";
 import { STATEFUL_NONCE_HEADER as STATEFUL_FORWARDING_NONCE_HEADER, STATEFUL_SIGNATURE_HEADER as STATEFUL_FORWARDING_SIGNATURE_HEADER, STATEFUL_TIMESTAMP_HEADER as STATEFUL_FORWARDING_TIMESTAMP_HEADER, verifyStatefulRequestSignature, } from "../stateful-signing.js";
 import { StatefulRoutingDeadlineError } from "../stateful/errors.js";
@@ -35,6 +36,7 @@ import { getStealthProfile } from "../stealth/profiles.js";
 import { APIFUSE_STREAM_DONE_EVENT, APIFUSE_STREAM_ERROR_EVENT, encodeSseEvent, error as streamError, } from "../stream.js";
 import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
+import { resolveServerTraceContextOptions } from "./trace-output.js";
 import { AuthFlowRequestSchema, OperationConnectionSchema, OperationRequestSchema, } from "./types.js";
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
@@ -363,6 +365,7 @@ function resolveNativeProxyPolicy(provider) {
     return undefined;
 }
 function createProviderContext(provider, request, operationId, options, state = createUnsupportedProviderRuntimeState(), proxyTelemetry, signal) {
+    const traceConfig = resolveTraceConfigFromEnv();
     const baseUrl = getProviderBaseUrl(provider);
     const stealthBaseUrl = getProviderStealthBaseUrl(provider);
     const stealthProfile = getProviderStealthProfile(provider);
@@ -443,7 +446,13 @@ function createProviderContext(provider, request, operationId, options, state =
                 },
             }
             : {}),
-        trace: createTraceContext(),
+        trace: traceConfig
+            ? createTraceContext(resolveServerTraceContextOptions(traceConfig, {
+                request_id: request.requestId,
+                provider_id: provider.id,
+                operation_id: operationId,
+            }))
+            : createTraceContext(),
         auth: createAuthStub(),
         ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
         stt: options.stt ?? createSttClientFromEnv(provider.stt),

package/dist/server/trace-output.d.ts

@@ -0,0 +1,4 @@
+import { type CreateTraceContextOptions } from "../runtime/trace.js";
+import type { TraceConfig } from "../types.js";
+/** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
+export declare function resolveServerTraceContextOptions(config: TraceConfig, resourceAttributes: Record<string, string>): CreateTraceContextOptions;

package/dist/server/trace-output.js

@@ -0,0 +1,20 @@
+import { resolveTraceContextOptions, } from "../runtime/trace.js";
+import { sanitizeSpanForOutput } from "../trace-sanitization.js";
+/** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
+export function resolveServerTraceContextOptions(config, resourceAttributes) {
+    const resolved = resolveTraceContextOptions(config);
+    const outputEnabled = config.enabled !== false && config.exporter !== "none";
+    const consoleHook = outputEnabled && (config.exporter === "console" || config.exporter === "json")
+        ? (span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes)))
+        : undefined;
+    const onSpan = consoleHook && resolved.onSpan
+        ? (span) => {
+            consoleHook(span);
+            resolved.onSpan?.(span);
+        }
+        : (consoleHook ?? resolved.onSpan);
+    return {
+        maxSpans: resolved.maxSpans,
+        onSpan,
+    };
+}

package/dist/trace-sanitization.d.ts

@@ -0,0 +1,5 @@
+import type { TraceSpan } from "./types.js";
+/** Span names are SDK-authored identifiers; retain them while preventing log injection. */
+export declare function sanitizeSpanNameForOutput(value: string): string;
+export declare function sanitizeTraceAttributes(attributes: Record<string, unknown>): Record<string, string | number | boolean>;
+export declare function sanitizeSpanForOutput(span: TraceSpan, additionalAttributes?: Record<string, string>): TraceSpan;

package/dist/trace-sanitization.js

@@ -0,0 +1,45 @@
+import { encodeDiagnosticControls, isSensitiveFixtureKey, REDACTED_FIXTURE_VALUE, sanitizeDiagnosticText, } from "./fixture-sanitization.js";
+const MAX_TRACE_TEXT_LENGTH = 300;
+function sanitizeTraceText(value) {
+    const encoded = sanitizeDiagnosticText(value);
+    return encoded.length > MAX_TRACE_TEXT_LENGTH
+        ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
+        : encoded;
+}
+/** Span names are SDK-authored identifiers; retain them while preventing log injection. */
+export function sanitizeSpanNameForOutput(value) {
+    const encoded = encodeDiagnosticControls(value);
+    return encoded.length > MAX_TRACE_TEXT_LENGTH
+        ? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
+        : encoded;
+}
+export function sanitizeTraceAttributes(attributes) {
+    return Object.fromEntries(Object.entries(attributes).map(([key, value]) => [
+        sanitizeTraceText(key),
+        isSensitiveFixtureKey(key)
+            ? REDACTED_FIXTURE_VALUE
+            : typeof value === "string"
+                ? sanitizeTraceText(value)
+                : typeof value === "number" || typeof value === "boolean"
+                    ? value
+                    : sanitizeTraceText(String(value)),
+    ]));
+}
+export function sanitizeSpanForOutput(span, additionalAttributes) {
+    // Keep this schema explicit so future fields are not silently added to a
+    // process output path before their trust boundary has been reviewed.
+    return {
+        id: span.id,
+        name: sanitizeSpanNameForOutput(span.name),
+        startedAt: span.startedAt,
+        endedAt: span.endedAt,
+        duration_ms: span.duration_ms,
+        status: span.status,
+        attributes: sanitizeTraceAttributes({
+            ...span.attributes,
+            ...(additionalAttributes ?? {}),
+        }),
+        ...(span.error !== undefined ? { error: sanitizeTraceText(span.error) } : {}),
+        ...(span.parentId !== undefined ? { parentId: span.parentId } : {}),
+    };
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-	"version": "2.2.0-beta.39",
+	"version": "2.2.0-beta.40",
 	"name": "@apifuse/provider-sdk",
 	"private": false,
 	"type": "module",

package/src/config/loader.ts

@@ -107,6 +107,8 @@ export type ProxyUserAgentSource = "declared" | "defaulted";
 
 export type ProxyResolutionTelemetryEvent = {
 	provider: ProxyVendorName;
+	/** Defaults to `"ok"` when omitted. */
+	outcome?: "ok" | "error";
 	userAgentSource?: ProxyUserAgentSource;
 	protocol?: ProxyProtocol;
 	cacheStatus: ProxyCacheStatus;
@@ -370,6 +372,7 @@ function telemetryForFailure(
 ): ProxyResolutionTelemetryEvent {
 	return {
 		provider: "smartproxy",
+		outcome: "error",
 		cacheStatus,
 		cacheHit: false,
 		resolutionMs: Math.max(0, Date.now() - startedAt),
@@ -916,7 +919,10 @@ export function resolvePolicyTransportAttemptCap(input: {
 	) {
 		return budget;
 	}
-	const span = Math.min(maxPolicyProxyPoolSpan(input.policy as ProviderProxyPolicy), resolvePolicyProxyPoolSpan(input.policy as ProviderProxyPolicy));
+	const span = Math.min(
+		maxPolicyProxyPoolSpan(input.policy as ProviderProxyPolicy),
+		resolvePolicyProxyPoolSpan(input.policy as ProviderProxyPolicy),
+	);
 	return Math.max(budget, span);
 }
 

package/src/fixture-sanitization.ts

@@ -200,7 +200,8 @@ function isCredentialBearingUrl(value: string): boolean {
 	}
 }
 
-function encodeDiagnosticControls(value: string): string {
+/** Encodes terminal/log control characters without applying value-level secret heuristics. */
+export function encodeDiagnosticControls(value: string): string {
 	let result = "";
 	for (const character of value) {
 		const code = character.codePointAt(0) ?? 0;

package/src/index.ts

@@ -177,7 +177,11 @@ export {
 } from "./runtime/instrumentation.js";
 export type { PrevalidateResult } from "./runtime/prevalidate.js";
 export { getProviderBaseUrl } from "./runtime/provider.js";
-export type { ProxyTelemetryLogPayload } from "./runtime/proxy-telemetry.js";
+export type {
+	ProxyTelemetryLogPayload,
+	ProxyTelemetryResolvedPayload,
+	ProxyTelemetryUnresolvedPayload,
+} from "./runtime/proxy-telemetry.js";
 export {
 	APIFUSE__CDP_POOL__URL,
 	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,

package/src/runtime/proxy-telemetry.ts

@@ -12,7 +12,8 @@ import type {
 
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 
-export type ProxyTelemetryLogPayload = {
+export type ProxyTelemetryResolvedPayload = {
+	kind: "resolved";
 	provider: ProxyVendorName;
 	userAgentSource?: ProxyUserAgentSource;
 	protocol?: ProxyProtocol;
@@ -52,6 +53,47 @@ export type ProxyTelemetryLogPayload = {
 	}[];
 };
 
+export type ProxyTelemetryUnresolvedPayload = {
+	kind: "unresolved";
+	/** Distinct vendors that failed resolution or recorded a failover, in order seen. */
+	vendors: ProxyVendorName[];
+	cacheStatus?: ProxyCacheStatus;
+	cacheHit?: boolean;
+	resolutionMs?: number;
+	allocatorMs?: number;
+	allocatorStatus?: number;
+	allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+	allocatorAttempts?: number;
+	lockWaitMs?: number;
+	redisReadMs?: number;
+	redisWriteMs?: number;
+	poolAgeMs?: number;
+	poolExpiresInMs?: number;
+	attempts?: number;
+	refreshes?: number;
+	failovers?: {
+		v: ProxyVendorName;
+		nx?: ProxyVendorName;
+		p: ProxyVendorFailoverTelemetryEvent["phase"];
+		r: ProxyVendorFailoverTelemetryEvent["reason"];
+		a?: number;
+	}[];
+	attemptSamples?: {
+		n: number;
+		a: number;
+		i?: number;
+		h?: string;
+		o: ProxyAttemptTelemetryEvent["outcome"];
+		c?: string;
+		s?: number;
+		d?: number;
+	}[];
+};
+
+export type ProxyTelemetryLogPayload =
+	| ProxyTelemetryResolvedPayload
+	| ProxyTelemetryUnresolvedPayload;
+
 type ProviderTelemetryHeader = {
 	v: 1;
 	proxy?: ProxyTelemetryLogPayload;
@@ -94,10 +136,13 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 	#events: ProxyResolutionTelemetryEvent[] = [];
 	#attempts: ProxyAttemptTelemetryEvent[] = [];
 	#failovers: ProxyVendorFailoverTelemetryEvent[] = [];
+	#unresolvedVendors: ProxyVendorName[] = [];
 
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
+		const outcome = event.outcome === "error" ? "error" : "ok";
 		this.#events.push({
 			provider: event.provider,
+			outcome,
 			...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
 			...(event.protocol ? { protocol: event.protocol } : {}),
 			cacheStatus: event.cacheStatus,
@@ -130,6 +175,9 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			refreshes:
 				event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
 		});
+		if (outcome === "error" && !this.#unresolvedVendors.includes(event.provider)) {
+			this.#unresolvedVendors.push(event.provider);
+		}
 	}
 
 	recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void {
@@ -141,6 +189,9 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			reason: event.reason,
 			...(event.attempt === undefined ? {} : { attempt: Math.max(0, Math.floor(event.attempt)) }),
 		});
+		if (!this.#unresolvedVendors.includes(event.vendor)) {
+			this.#unresolvedVendors.push(event.vendor);
+		}
 	}
 
 	recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void {
@@ -163,11 +214,94 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 
 	toLogPayload(): ProxyTelemetryLogPayload | undefined {
 		const [first, ...rest] = this.#events;
-		if (!first) return undefined;
+		const okEvents = this.#events.filter((event) => event.outcome !== "error");
+		const attemptSamples = this.#attempts.map((attempt, index) => ({
+			n: index + 1,
+			a: attempt.attempt,
+			...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
+			...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
+			o: attempt.outcome,
+			...(attempt.errorCode ? { c: attempt.errorCode } : {}),
+			...(attempt.status === undefined ? {} : { s: attempt.status }),
+			...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
+		}));
+		const failovers = this.#failovers.map((failover) => ({
+			v: failover.vendor,
+			...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+			p: failover.phase,
+			r: failover.reason,
+			...(failover.attempt === undefined ? {} : { a: failover.attempt }),
+		}));
 
-		// The serving vendor/protocol is the last recorded resolution (a failed
-		// vendor records first, the vendor that served records last).
-		const serving = this.#events[this.#events.length - 1] ?? first;
+		if (okEvents.length === 0) {
+			if (!first && failovers.length === 0) return undefined;
+			const failureEvents = this.#events.filter((event) => event.outcome === "error");
+			const [firstFailure, ...remainingFailures] = failureEvents;
+			const aggregate = firstFailure
+				? remainingFailures.reduce<ProxyResolutionTelemetryEvent>(
+						(acc, event) => ({
+							provider: event.provider,
+							outcome: "error",
+							cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
+							cacheHit: acc.cacheHit && event.cacheHit,
+							resolutionMs: acc.resolutionMs + event.resolutionMs,
+							allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
+							allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
+							allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
+							allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
+							lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
+							redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
+							redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
+							poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
+							poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
+							attempts: acc.attempts + event.attempts,
+							refreshes: sumOptional(acc.refreshes, event.refreshes),
+						}),
+						firstFailure,
+					)
+				: undefined;
+			return {
+				kind: "unresolved",
+				vendors: [...this.#unresolvedVendors],
+				...(aggregate
+					? {
+							cacheStatus: aggregate.cacheStatus,
+							cacheHit: aggregate.cacheHit,
+							resolutionMs: aggregate.resolutionMs,
+							...(aggregate.allocatorMs !== undefined
+								? { allocatorMs: aggregate.allocatorMs }
+								: {}),
+							...(aggregate.allocatorStatus !== undefined
+								? { allocatorStatus: aggregate.allocatorStatus }
+								: {}),
+							...(aggregate.allocatorBodyClass !== undefined
+								? { allocatorBodyClass: aggregate.allocatorBodyClass }
+								: {}),
+							...(aggregate.allocatorAttempts !== undefined
+								? { allocatorAttempts: aggregate.allocatorAttempts }
+								: {}),
+							...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
+							...(aggregate.redisReadMs !== undefined
+								? { redisReadMs: aggregate.redisReadMs }
+								: {}),
+							...(aggregate.redisWriteMs !== undefined
+								? { redisWriteMs: aggregate.redisWriteMs }
+								: {}),
+							...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
+							...(aggregate.poolExpiresInMs !== undefined
+								? { poolExpiresInMs: aggregate.poolExpiresInMs }
+								: {}),
+							attempts: aggregate.attempts,
+							...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
+						}
+					: {}),
+				...(failovers.length > 0 ? { failovers } : {}),
+				...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+			};
+		}
+
+		// The serving vendor/protocol is the last successful resolution.
+		const serving = okEvents[okEvents.length - 1] ?? first;
 		const vendors: ProxyVendorName[] = [];
 		for (const event of this.#events) {
 			if (!vendors.includes(event.provider)) vendors.push(event.provider);
@@ -195,6 +329,7 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			first,
 		);
 		return {
+			kind: "resolved",
 			provider: serving.provider,
 			...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
 			...(serving.protocol ? { protocol: serving.protocol } : {}),
@@ -220,32 +355,9 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 				: {}),
 			attempts: aggregate.attempts,
 			...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
-			...(this.#attempts.length > 0
-				? {
-						attemptSamples: this.#attempts.map((attempt, index) => ({
-							n: index + 1,
-							a: attempt.attempt,
-							...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
-							...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
-							o: attempt.outcome,
-							...(attempt.errorCode ? { c: attempt.errorCode } : {}),
-							...(attempt.status === undefined ? {} : { s: attempt.status }),
-							...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
-						})),
-					}
-				: {}),
+			...(attemptSamples.length > 0 ? { attemptSamples } : {}),
 			...(vendors.length > 1 ? { vendors } : {}),
-			...(this.#failovers.length > 0
-				? {
-						failovers: this.#failovers.map((failover) => ({
-							v: failover.vendor,
-							...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
-							p: failover.phase,
-							r: failover.reason,
-							...(failover.attempt === undefined ? {} : { a: failover.attempt }),
-						})),
-					}
-				: {}),
+			...(failovers.length > 0 ? { failovers } : {}),
 		};
 	}
 

package/src/runtime/trace-config.ts

@@ -0,0 +1,77 @@
+import type { TraceConfig } from "../types.js";
+
+/** SDK-owned environment variable names for server trace output. */
+export const APIFUSE__TRACE__ENABLED = "APIFUSE__TRACE__ENABLED";
+export const APIFUSE__TRACE__EXPORTER = "APIFUSE__TRACE__EXPORTER";
+
+type EnvLike = Record<string, string | undefined>;
+
+const TRACE_EXPORTER_LOOKUP: Record<Exclude<NonNullable<TraceConfig["exporter"]>, "otlp">, true> = {
+	console: true,
+	json: true,
+	none: true,
+};
+const TRACE_EXPORTERS = new Set(Object.keys(TRACE_EXPORTER_LOOKUP));
+
+const emittedWarnings = new Set<string>();
+
+function warnOnce(key: string, message: string): void {
+	if (emittedWarnings.has(key)) return;
+	emittedWarnings.add(key);
+	console.warn(message);
+}
+
+function parseEnabled(raw: string | undefined): boolean | undefined {
+	if (raw === undefined) return undefined;
+	switch (raw.trim().toLowerCase()) {
+		case "1":
+		case "true":
+		case "yes":
+		case "on":
+			return true;
+		case "0":
+		case "false":
+		case "no":
+		case "off":
+			return false;
+		default:
+			warnOnce(
+				APIFUSE__TRACE__ENABLED,
+				"[apifuse] Invalid APIFUSE__TRACE__ENABLED; falling back to disabled tracing.",
+			);
+			return false;
+	}
+}
+
+/**
+ * Resolve server trace output configuration from SDK-owned environment
+ * variables. Invalid exporter values fail closed so a provider cannot crash at
+ * startup because of an observability setting.
+ */
+export function resolveTraceConfigFromEnv(env: EnvLike = process.env): TraceConfig | undefined {
+	const enabledRaw = env[APIFUSE__TRACE__ENABLED];
+	const exporterRaw = env[APIFUSE__TRACE__EXPORTER];
+
+	if (enabledRaw === undefined && exporterRaw === undefined) {
+		return undefined;
+	}
+
+	const enabled = parseEnabled(enabledRaw);
+	const normalizedExporter = exporterRaw?.trim().toLowerCase();
+	const exporter = TRACE_EXPORTERS.has(normalizedExporter as NonNullable<TraceConfig["exporter"]>)
+		? (normalizedExporter as NonNullable<TraceConfig["exporter"]>)
+		: exporterRaw === undefined
+			? undefined
+			: "none";
+	if (exporterRaw !== undefined && exporter === "none" && normalizedExporter !== "none") {
+		warnOnce(
+			APIFUSE__TRACE__EXPORTER,
+			`[apifuse] Invalid APIFUSE__TRACE__EXPORTER value "${normalizedExporter ?? exporterRaw}" (OTLP is unsupported for server output); supported exporters are "console", "json", and "none"; falling back to exporter "none".`,
+		);
+	}
+
+	return {
+		...(enabled !== undefined ? { enabled } : {}),
+		...(exporter !== undefined ? { exporter } : {}),
+	};
+}

package/src/server/index.ts

@@ -5,7 +5,11 @@ export type {
 	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
 } from "../config/loader.js";
-export type { ProxyTelemetryLogPayload } from "../runtime/proxy-telemetry.js";
+export type {
+	ProxyTelemetryLogPayload,
+	ProxyTelemetryResolvedPayload,
+	ProxyTelemetryUnresolvedPayload,
+} from "../runtime/proxy-telemetry.js";
 export {
 	createServerApp,
 	createServerAppAsync,

package/src/server/serve-implementation.ts

@@ -74,6 +74,7 @@ import { StealthCookieJar } from "../runtime/stealth-cookies.js";
 import type * as StealthRuntimeModule from "../runtime/stealth.js";
 import { createSttClientFromEnv } from "../runtime/stt.js";
 import { createTraceContext } from "../runtime/trace.js";
+import { resolveTraceConfigFromEnv } from "../runtime/trace-config.js";
 import { parseSchema } from "../schema.js";
 import {
 	STATEFUL_NONCE_HEADER as STATEFUL_FORWARDING_NONCE_HEADER,
@@ -116,6 +117,7 @@ import type {
 import { VALID_OPERATION_ERROR_STATUSES } from "../types.js";
 import type { SelfTestCancellationLogEvent } from "./self-test.js";
 import { resolveSelfTestMasterSecrets } from "./self-test-token.js";
+import { resolveServerTraceContextOptions } from "./trace-output.js";
 import {
 	type AuthFlowRequest,
 	AuthFlowRequestSchema,
@@ -608,6 +610,7 @@ function createProviderContext(
 	proxyTelemetry?: ProxyTelemetryCollector,
 	signal?: AbortSignal,
 ): ProviderContext {
+	const traceConfig = resolveTraceConfigFromEnv();
 	const baseUrl = getProviderBaseUrl(provider);
 	const stealthBaseUrl = getProviderStealthBaseUrl(provider);
 	const stealthProfile = getProviderStealthProfile(provider);
@@ -711,7 +714,15 @@ function createProviderContext(
 					},
 				}
 			: {}),
-		trace: createTraceContext(),
+		trace: traceConfig
+			? createTraceContext(
+					resolveServerTraceContextOptions(traceConfig, {
+						request_id: request.requestId,
+						provider_id: provider.id,
+						operation_id: operationId,
+					}),
+				)
+			: createTraceContext(),
 		auth: createAuthStub(),
 		ocr: options.ocr ?? createOcrClientFromEnv(provider.ocr),
 		stt: options.stt ?? createSttClientFromEnv(provider.stt),

package/src/server/trace-output.ts

@@ -0,0 +1,32 @@
+import {
+	resolveTraceContextOptions,
+	type CreateTraceContextOptions,
+	type Span,
+} from "../runtime/trace.js";
+import { sanitizeSpanForOutput } from "../trace-sanitization.js";
+import type { TraceConfig } from "../types.js";
+
+/** Server-only trace output policy. Shared programmatic trace callers stay in-memory. */
+export function resolveServerTraceContextOptions(
+	config: TraceConfig,
+	resourceAttributes: Record<string, string>,
+): CreateTraceContextOptions {
+	const resolved = resolveTraceContextOptions(config);
+	const outputEnabled = config.enabled !== false && config.exporter !== "none";
+	const consoleHook =
+		outputEnabled && (config.exporter === "console" || config.exporter === "json")
+			? (span: Span) => console.log(JSON.stringify(sanitizeSpanForOutput(span, resourceAttributes)))
+			: undefined;
+	const onSpan =
+		consoleHook && resolved.onSpan
+			? (span: Span) => {
+					consoleHook(span);
+					resolved.onSpan?.(span);
+				}
+			: (consoleHook ?? resolved.onSpan);
+
+	return {
+		maxSpans: resolved.maxSpans,
+		onSpan,
+	};
+}

package/src/trace-sanitization.ts

@@ -0,0 +1,63 @@
+import {
+	encodeDiagnosticControls,
+	isSensitiveFixtureKey,
+	REDACTED_FIXTURE_VALUE,
+	sanitizeDiagnosticText,
+} from "./fixture-sanitization.js";
+import type { TraceSpan } from "./types.js";
+
+const MAX_TRACE_TEXT_LENGTH = 300;
+
+function sanitizeTraceText(value: string): string {
+	const encoded = sanitizeDiagnosticText(value);
+	return encoded.length > MAX_TRACE_TEXT_LENGTH
+		? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
+		: encoded;
+}
+
+/** Span names are SDK-authored identifiers; retain them while preventing log injection. */
+export function sanitizeSpanNameForOutput(value: string): string {
+	const encoded = encodeDiagnosticControls(value);
+	return encoded.length > MAX_TRACE_TEXT_LENGTH
+		? `${encoded.slice(0, MAX_TRACE_TEXT_LENGTH)}… [truncated]`
+		: encoded;
+}
+
+export function sanitizeTraceAttributes(
+	attributes: Record<string, unknown>,
+): Record<string, string | number | boolean> {
+	return Object.fromEntries(
+		Object.entries(attributes).map(([key, value]) => [
+			sanitizeTraceText(key),
+			isSensitiveFixtureKey(key)
+				? REDACTED_FIXTURE_VALUE
+				: typeof value === "string"
+					? sanitizeTraceText(value)
+					: typeof value === "number" || typeof value === "boolean"
+						? value
+						: sanitizeTraceText(String(value)),
+		]),
+	);
+}
+
+export function sanitizeSpanForOutput(
+	span: TraceSpan,
+	additionalAttributes?: Record<string, string>,
+): TraceSpan {
+	// Keep this schema explicit so future fields are not silently added to a
+	// process output path before their trust boundary has been reviewed.
+	return {
+		id: span.id,
+		name: sanitizeSpanNameForOutput(span.name),
+		startedAt: span.startedAt,
+		endedAt: span.endedAt,
+		duration_ms: span.duration_ms,
+		status: span.status,
+		attributes: sanitizeTraceAttributes({
+			...span.attributes,
+			...(additionalAttributes ?? {}),
+		}),
+		...(span.error !== undefined ? { error: sanitizeTraceText(span.error) } : {}),
+		...(span.parentId !== undefined ? { parentId: span.parentId } : {}),
+	};
+}