@hue-run/sdk 0.1.4 → 0.1.5

package/dist/transport.js

@@ -5,7 +5,32 @@ import { LogsExporterMetricsHelper, ProtobufLogsSerializer, ProtobufTraceSeriali
 import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace";
 import { BatchLogRecordProcessor, } from "@opentelemetry/sdk-logs";
 import { MAX_BODY_BYTES, validateOptions } from "./config.js";
+import { estimateRecordBytes } from "./safety.js";
+import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { redactLog, redactSpan } from "./privacy.js";
+function recordData(record, signal) {
+    if (signal === "traces") {
+        const span = record;
+        return {
+            name: span.name,
+            attributes: span.attributes,
+            events: span.events,
+            links: span.links,
+            status: span.status,
+            resource: span.resource.attributes,
+            scope: span.instrumentationScope,
+        };
+    }
+    const log = record;
+    return {
+        body: log.body,
+        attributes: log.attributes,
+        eventName: log.eventName,
+        severityText: log.severityText,
+        resource: log.resource.attributes,
+        scope: log.instrumentationScope,
+    };
+}
 export class HueExportError extends Error {
     issues;
     report;
@@ -28,8 +53,13 @@ export class HueTransport {
     accepted = { traces: 0, logs: 0 };
     rejected = { traces: 0, logs: 0 };
     failed = { traces: 0, logs: 0 };
-    spans = new Set();
-    logs = new Set();
+    spans = new Map();
+    logs = new Map();
+    pendingBytes = 0;
+    dropped = { traces: 0, logs: 0 };
+    instrumentationFailures = 0;
+    diagnosticPending = false;
+    lastDiagnosticAt = -Infinity;
     traceExporter;
     logExporter;
     closed = false;
@@ -40,6 +70,11 @@ export class HueTransport {
         Object.defineProperty(this, "options", { enumerable: false });
         this.traceExporter = new ReportingExporter(this, "traces", ProtobufTraceSerializer, TraceExporterMetricsHelper, (span, cache) => redactSpan(span, this.options, cache));
         this.logExporter = new ReportingExporter(this, "logs", ProtobufLogsSerializer, LogsExporterMetricsHelper, (log, cache) => redactLog(log, this.options, cache));
+        if (this.options.enabled === false) {
+            this.spanProcessor = { onStart() { }, onEnd() { }, async forceFlush() { }, async shutdown() { } };
+            this.logRecordProcessor = { onEmit() { }, async forceFlush() { }, async shutdown() { } };
+            return;
+        }
         const batching = {
             maxQueueSize: 2048,
             maxExportBatchSize: 128,
@@ -49,22 +84,49 @@ export class HueTransport {
         const spans = new BatchSpanProcessor({ exporter: this.traceExporter, ...batching });
         const logs = new BatchLogRecordProcessor({ exporter: this.logExporter, ...batching });
         this.spanProcessor = {
-            onStart: (span, parent) => spans.onStart(span, parent),
+            onStart: (span, parent) => {
+                try {
+                    spans.onStart(span, parent);
+                }
+                catch {
+                    this.instrumentationFailure();
+                }
+            },
             onEnd: (span) => {
-                if (!(span.spanContext().traceFlags & 1))
-                    return;
-                if (!this.enqueue("traces", span))
-                    return;
-                spans.onEnd(span);
+                let admitted;
+                try {
+                    if (!(span.spanContext().traceFlags & 1))
+                        return;
+                    const queued = this.enqueue("traces", span);
+                    if (!queued)
+                        return;
+                    admitted = queued;
+                    spans.onEnd(admitted);
+                }
+                catch {
+                    if (admitted)
+                        this.finish("traces", [admitted]);
+                    this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record");
+                }
             },
             forceFlush: () => spans.forceFlush(),
             shutdown: () => spans.shutdown(),
         };
         this.logRecordProcessor = {
             onEmit: (log) => {
-                if (!this.enqueue("logs", log))
-                    return;
-                logs.onEmit(log);
+                let admitted;
+                try {
+                    const queued = this.enqueue("logs", log);
+                    if (!queued)
+                        return;
+                    admitted = queued;
+                    logs.onEmit(queued);
+                }
+                catch {
+                    if (admitted)
+                        this.finish("logs", [admitted]);
+                    this.issue("logs", "invalid", 1, "Telemetry processor could not accept a record");
+                }
             },
             forceFlush: () => logs.forceFlush(),
             shutdown: () => logs.shutdown(),
@@ -76,26 +138,40 @@ export class HueTransport {
             this.issue(signal, "dropped", 1, this.closed
                 ? "Telemetry emitted after transport shutdown"
                 : "Telemetry queue reached 2048 records");
-            return false;
+            return undefined;
+        }
+        try {
+            const remaining = this.options.maxQueueBytes - this.pendingBytes;
+            const snapshot = signal === "traces"
+                ? snapshotSpan(record, remaining)
+                : snapshotLog(record, remaining);
+            this.pendingBytes += snapshot.bytes;
+            if (signal === "traces")
+                this.spans.set(snapshot.record, snapshot.bytes);
+            else
+                this.logs.set(snapshot.record, snapshot.bytes);
+            if (snapshot.unresolvedResource)
+                this.issue(signal, "warning", 0, "Unresolved resource attributes omitted from the telemetry snapshot");
+            return snapshot.record;
+        }
+        catch {
+            this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data");
+            return undefined;
         }
-        if (signal === "traces")
-            this.spans.add(record);
-        else
-            this.logs.add(record);
-        return true;
     }
     finish(signal, records) {
         for (const record of records) {
-            if (signal === "traces")
-                this.spans.delete(record);
-            else
-                this.logs.delete(record);
+            const pending = signal === "traces" ? this.spans : this.logs;
+            this.pendingBytes -= pending.get(record) ?? 0;
+            pending.delete(record);
         }
     }
     acceptedRecords(signal, count) {
         this.accepted[signal] += count;
     }
     issue(signal, kind, count, message, status) {
+        if (kind === "dropped")
+            this.dropped[signal] += count;
         if (kind === "rejected")
             this.rejected[signal] += count;
         else if (kind !== "warning")
@@ -113,13 +189,26 @@ export class HueTransport {
         this.issues.push(issue);
         if (this.issues.length > 128)
             this.issues.shift();
-        try {
-            this.options.onExportIssue?.({ ...issue });
-        }
-        catch {
-            /* Diagnostics callbacks cannot interrupt the customer's application. */
+        // One diagnostic task at a time, at most once a second. No unbounded promise
+        // queue if a user callback never settles; all issues remain in counts/history.
+        if (this.options.onExportIssue &&
+            !this.diagnosticPending &&
+            Date.now() - this.lastDiagnosticAt >= 1000) {
+            this.diagnosticPending = true;
+            this.lastDiagnosticAt = Date.now();
+            void Promise.resolve()
+                .then(() => this.options.onExportIssue?.({ ...issue }))
+                .then(() => {
+                this.diagnosticPending = false;
+            }, () => {
+                this.diagnosticPending = false;
+            });
         }
     }
+    instrumentationFailure(signal = "traces") {
+        this.instrumentationFailures++;
+        this.issue(signal, "invalid", 0, "Telemetry capture or instrumentation failed; application execution was preserved");
+    }
     getReport() {
         return {
             acceptedSpans: this.accepted.traces,
@@ -130,6 +219,10 @@ export class HueTransport {
             failedLogs: this.failed.logs,
             pendingSpans: this.spans.size,
             pendingLogs: this.logs.size,
+            droppedSpans: this.dropped.traces,
+            droppedLogs: this.dropped.logs,
+            pendingBytes: this.pendingBytes,
+            instrumentationFailures: this.instrumentationFailures,
         };
     }
     getIssues() {
@@ -208,17 +301,40 @@ class ReportingExporter {
             .finally(() => {
             this.transport.finish(this.signal, records);
             this.pending.delete(work);
-        });
+        })
+            .catch(() => { });
         this.pending.add(work);
     }
     async exportRecords(records) {
         const accepted = [];
         const cache = new WeakMap();
         let failed = false;
+        let redactedBytes = 0;
+        const resourceDeadline = Date.now() + this.transport.options.timeoutMillis;
         for (const record of records) {
             try {
-                await record.resource.waitForAsyncAttributes?.();
-                accepted.push(this.redact(record, cache));
+                const ready = record.resource.waitForAsyncAttributes?.();
+                if (ready) {
+                    let timer;
+                    try {
+                        await Promise.race([
+                            ready,
+                            new Promise((_resolve, reject) => {
+                                timer = setTimeout(() => reject(new Error("Resource deadline exceeded")), Math.max(1, resourceDeadline - Date.now()));
+                            }),
+                        ]);
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                }
+                const redacted = this.redact(record, cache);
+                const bytes = 512 +
+                    estimateRecordBytes(recordData(redacted, this.signal), this.transport.options.maxQueueBytes - redactedBytes);
+                if (redactedBytes + bytes > this.transport.options.maxQueueBytes)
+                    throw new RangeError("Redacted batch exceeds byte budget");
+                redactedBytes += bytes;
+                accepted.push(redacted);
             }
             catch {
                 failed = true;
@@ -227,6 +343,15 @@ class ReportingExporter {
         }
         let batch = [];
         for (const record of accepted) {
+            let recordBytes;
+            try {
+                recordBytes = this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
+            }
+            catch {
+                failed = true;
+                this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be serialized");
+                continue;
+            }
             const candidate = [...batch, record];
             // Leave room for gzip headers/blocks when otherwise incompressible data is near the wire cap.
             if ((this.serializer.serializeRequest(candidate)?.byteLength ?? 0) <= MAX_BODY_BYTES - 1024) {
@@ -236,7 +361,7 @@ class ReportingExporter {
             if (batch.length && !(await this.send(batch)))
                 failed = true;
             batch = [];
-            if ((this.serializer.serializeRequest([record])?.byteLength ?? 0) > MAX_BODY_BYTES - 1024) {
+            if (recordBytes > MAX_BODY_BYTES - 1024) {
                 failed = true;
                 this.transport.issue(this.signal, "invalid", 1, "Telemetry record exceeds the 1 MiB request limit");
             }
@@ -252,9 +377,17 @@ class ReportingExporter {
         const options = this.transport.options;
         let rejected = 0;
         let validResponse = true;
+        let receivedResponse = false;
+        let expired = false;
+        const agents = new Set();
+        const deadline = Date.now() + options.timeoutMillis;
+        let timer;
         const serializer = {
             serializeRequest: (data) => this.serializer.serializeRequest(data),
             deserializeResponse: (bytes) => {
+                if (expired)
+                    return {};
+                receivedResponse = true;
                 try {
                     const response = this.serializer.deserializeResponse(bytes);
                     const partial = response.partialSuccess;
@@ -283,11 +416,33 @@ class ReportingExporter {
             timeoutMillis: options.timeoutMillis,
             concurrencyLimit: 1,
             compression: CompressionAlgorithm.GZIP,
+            httpAgentOptions: async (protocol) => {
+                if (expired || Date.now() >= deadline)
+                    throw new Error("Hue export deadline exceeded");
+                const { Agent } = await import(protocol === "https:" ? "node:https" : "node:http");
+                const agent = new Agent({ keepAlive: false });
+                agents.add(agent);
+                if (expired)
+                    agent.destroy();
+                return agent;
+            },
         }, this.signal === "traces" ? "TRACES" : "LOGS", `v1/${this.signal}`, { "Content-Type": "application/x-protobuf" }), serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
         const exporter = new OTLPExporterBase(delegate);
         try {
-            const result = await new Promise((resolve) => exporter.export(records, resolve));
+            const result = await new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    expired = true;
+                    for (const agent of agents)
+                        agent.destroy();
+                    resolve({ code: ExportResultCode.FAILED });
+                }, Math.max(1, deadline - Date.now()));
+                exporter.export(records, resolve);
+            });
             if (result.code === ExportResultCode.SUCCESS) {
+                if (!receivedResponse) {
+                    this.transport.issue(this.signal, "failed", records.length, "Hue response ended without a complete OTLP acknowledgement; acceptance is uncertain");
+                    return false;
+                }
                 if (validResponse)
                     this.transport.acceptedRecords(this.signal, records.length - rejected);
                 return validResponse;
@@ -305,7 +460,12 @@ class ReportingExporter {
             return false;
         }
         finally {
-            await exporter.shutdown();
+            clearTimeout(timer);
+            for (const agent of agents)
+                agent.destroy();
+            // Delegate cleanup cannot extend the hard request wait. Sockets are closed
+            // and the cleanup promise is always observed, even after a caller timeout.
+            void exporter.shutdown().catch(() => { });
         }
     }
     async forceFlush() {

package/dist/types.d.ts

@@ -4,17 +4,26 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
 export type Signal = "traces" | "logs";
-export interface HueOptions {
-    apiKey: string;
-    serviceName: string;
+interface SharedHueOptions {
     captureContent: boolean;
     baseUrl?: string;
     serviceVersion?: string;
     /** Runs on string values before Hue export, including custom attribute values. */
     redact?: (value: string, path: string) => string;
-    onExportIssue?: (issue: ExportIssue) => void;
+    onExportIssue?: (issue: ExportIssue) => void | Promise<void>;
     timeoutMillis?: number;
+    /** Aggregate estimated retained telemetry bytes across both signals, including in-flight work. Default 8 MiB. */
+    maxQueueBytes?: number;
 }
+export type HueOptions = SharedHueOptions & ({
+    enabled?: true;
+    apiKey: string;
+    serviceName: string;
+} | {
+    enabled: false;
+    apiKey?: string;
+    serviceName?: string;
+});
 export interface ExportIssue {
     sequence: number;
     signal: Signal;
@@ -32,6 +41,19 @@ export interface ExportReport {
     failedLogs: number;
     pendingSpans: number;
     pendingLogs: number;
+    droppedSpans: number;
+    droppedLogs: number;
+    pendingBytes: number;
+    instrumentationFailures: number;
+}
+export interface SafeLifecycleOptions {
+    /** Caller wait budget, 1–60000 ms. Default 1000. Does not cancel borrowed providers. */
+    timeoutMillis?: number;
+}
+export interface SafeLifecycleResult {
+    ok: boolean;
+    timedOut: boolean;
+    report: ExportReport;
 }
 export interface SpanOptions {
     kind?: SpanKind;
@@ -82,3 +104,4 @@ export interface TraceVerification {
     verified: boolean;
     receipt: TraceReceipt | null;
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "license": "MIT",
   "publishConfig": {
@@ -68,7 +68,7 @@
   "peerDependencies": {
     "@ai-sdk/otel": "^1.0.99",
     "@opentelemetry/api": "^1.9.1",
-    "ai": "^7.0.99"
+    "ai": "^6.0.0 || ^7.0.99"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/otel": {