@hue-run/sdk 0.5.1 → 0.7.0

package/dist/transport.js

@@ -1,10 +1,12 @@
+import { gzip } from "node:zlib";
 import { ExportResultCode } from "@opentelemetry/core";
-import { CompressionAlgorithm, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
-import { createOtlpHttpExportDelegate } from "@opentelemetry/otlp-exporter-base/node-http";
+import { createOtlpNetworkExportDelegate, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
+import { createOtlpHttpExporterMetrics } from "@opentelemetry/otlp-exporter-base/node-http";
 import { LogsExporterMetricsHelper, ProtobufLogsSerializer, ProtobufTraceSerializer, TraceExporterMetricsHelper, } from "@opentelemetry/otlp-transformer";
 import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace";
 import { BatchLogRecordProcessor, } from "@opentelemetry/sdk-logs";
 import { isInsecureOrigin, MAX_BODY_BYTES, validateOptions } from "./config.js";
+import { announcesLiveSpan, LIVE_SPAN_INTERVAL_MILLIS, MAX_LIVE_SPANS, pendingPlaceholder, PLACEHOLDERS_HEADER, withoutPlaceholderMarkers, } from "./live-spans.js";
 import { estimateRecordBytes } from "./safety.js";
 import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { redactLog, redactSpan } from "./privacy.js";
@@ -83,9 +85,20 @@ export class HueTransport {
     closed = false;
     shutdownPromise;
     flushPromise;
+    // Open spans not yet announced. Each is considered once, at the next tick after it starts.
+    live = new Set();
+    liveTimer;
+    liveSpans;
+    placeholdersRejected = false;
+    // Admitted placeholder snapshots and the marker attributes added after redaction.
+    placeholders = new WeakMap();
+    // The running span each admitted placeholder announces, so one it has outlived is not sent.
+    placeholderSources = new WeakMap();
+    batchSpans;
     constructor(options) {
         this.options = validateOptions(options);
         Object.defineProperty(this, "options", { enumerable: false });
+        this.liveSpans = this.options.enabled !== false && this.options.liveSpans;
         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) {
@@ -103,6 +116,7 @@ export class HueTransport {
         };
         const spans = new BatchSpanProcessor({ exporter: this.traceExporter, ...batching });
         const logs = new BatchLogRecordProcessor({ exporter: this.logExporter, ...batching });
+        this.batchSpans = spans;
         this.spanProcessor = {
             onStart: (span, parent) => {
                 try {
@@ -111,8 +125,11 @@ export class HueTransport {
                 catch {
                     this.instrumentationFailure();
                 }
+                this.track(span);
             },
             onEnd: (span) => {
+                if (this.live.delete(span) && !this.live.size)
+                    this.stopLiveTimer();
                 let admitted;
                 try {
                     if (!(span.spanContext().traceFlags & 1))
@@ -130,7 +147,10 @@ export class HueTransport {
                 }
             },
             forceFlush: () => spans.forceFlush(),
-            shutdown: () => spans.shutdown(),
+            shutdown: () => {
+                this.stopLiveSpans();
+                return spans.shutdown();
+            },
         };
         this.logRecordProcessor = {
             onEmit: (log) => {
@@ -152,8 +172,15 @@ export class HueTransport {
             shutdown: () => logs.shutdown(),
         };
     }
-    enqueue(signal, record) {
+    /**
+     * Advisory records (placeholders) are admitted only while the queue is under a quarter of its
+     * record and byte budgets, so they never take more than a quarter from real records. They are
+     * skipped silently.
+     */
+    enqueue(signal, record, advisory = false) {
         const pending = signal === "traces" ? this.spans : this.logs;
+        if (advisory && (this.closed || pending.size >= 2048 / 4))
+            return undefined;
         if (this.closed || pending.size >= 2048) {
             this.issue(signal, "dropped", 1, this.closed
                 ? "Telemetry emitted after transport shutdown"
@@ -161,7 +188,8 @@ export class HueTransport {
             return undefined;
         }
         try {
-            const remaining = this.options.maxQueueBytes - this.pendingBytes;
+            const remaining = (advisory ? this.options.maxQueueBytes / 4 : this.options.maxQueueBytes) -
+                this.pendingBytes;
             const snapshot = signal === "traces"
                 ? snapshotSpan(record, remaining)
                 : snapshotLog(record, remaining);
@@ -170,15 +198,94 @@ export class HueTransport {
                 this.spans.set(snapshot.record, snapshot.bytes);
             else
                 this.logs.set(snapshot.record, snapshot.bytes);
-            if (snapshot.unresolvedResource)
+            if (snapshot.unresolvedResource && !advisory)
                 this.issue(signal, "warning", 0, "Unresolved resource attributes omitted from the telemetry snapshot");
             return snapshot.record;
         }
         catch {
+            if (advisory)
+                return undefined;
             this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data");
             return undefined;
         }
     }
+    track(span) {
+        try {
+            if (!this.liveSpans || this.live.size >= MAX_LIVE_SPANS)
+                return;
+            if (!(span.spanContext().traceFlags & 1) || !span.isRecording() || !announcesLiveSpan(span))
+                return;
+            this.live.add(span);
+            if (!this.liveTimer) {
+                const timer = setInterval(() => this.announceLiveSpans(), LIVE_SPAN_INTERVAL_MILLIS);
+                timer.unref();
+                this.liveTimer = timer;
+            }
+        }
+        catch {
+            // Live announcements are advisory. They never report failures or affect the span.
+        }
+    }
+    /** Placeholders are built lazily, so input set right after a span starts is included. */
+    announceLiveSpans() {
+        for (const span of this.live) {
+            this.live.delete(span);
+            try {
+                // Ended without reaching onEnd: a wrapping processor filtered it, so no real span follows.
+                if (!this.liveSpans || span.ended || !this.batchSpans)
+                    continue;
+                const { record, markers } = pendingPlaceholder(span);
+                const admitted = this.enqueue("traces", record, true);
+                if (!admitted)
+                    continue;
+                this.placeholders.set(admitted, markers);
+                this.placeholderSources.set(admitted, span);
+                try {
+                    this.batchSpans.onEnd(admitted);
+                }
+                catch {
+                    this.finish("traces", [admitted]);
+                }
+            }
+            catch {
+                // Skipped silently, like any placeholder the queue has no room for.
+            }
+        }
+        if (!this.live.size)
+            this.stopLiveTimer();
+    }
+    stopLiveTimer() {
+        clearInterval(this.liveTimer);
+        this.liveTimer = undefined;
+    }
+    stopLiveSpans() {
+        this.liveSpans = false;
+        this.live.clear();
+        this.stopLiveTimer();
+    }
+    /** @internal Exporter callback: marker attributes when `record` is an admitted placeholder. */
+    placeholderMarkers(record) {
+        return this.placeholders.get(record);
+    }
+    /** @internal Exporter callback: whether a placeholder's span has ended, so it announces nothing. */
+    placeholderSettled(record) {
+        return this.placeholderSources.get(record)?.ended === true;
+    }
+    /** @internal Exporter callback: false once the receiver refused placeholders; queued ones are then dropped. */
+    sendsPlaceholders() {
+        return !this.placeholdersRejected;
+    }
+    /**
+     * @internal Exporter callback: a receiver without placeholder support rejects each by its zero
+     * end time. Stops announcing for this transport and records one warning.
+     */
+    rejectPlaceholders(count) {
+        this.stopLiveSpans();
+        if (this.placeholdersRejected)
+            return;
+        this.placeholdersRejected = true;
+        this.issue("traces", "warning", count, "This Hue server does not accept in-progress span placeholders; live spans are disabled");
+    }
     /** @internal Exporter callback: releases queued records after an export attempt settles. */
     finish(signal, records) {
         for (const record of records) {
@@ -345,13 +452,52 @@ class ReportingExporter {
             .catch(() => { });
         this.pending.add(work);
     }
+    /** Real records first, then placeholders whose real span is not already in this batch. */
+    ordered(records) {
+        if (this.signal !== "traces")
+            return records.map((record) => ({ record }));
+        const real = [];
+        const placeholders = [];
+        for (const record of records) {
+            const markers = this.transport.placeholderMarkers(record);
+            if (markers)
+                placeholders.push({ record, markers });
+            else
+                real.push({ record });
+        }
+        if (!placeholders.length || !this.transport.sendsPlaceholders())
+            return real;
+        const ended = new Set(real.map(({ record }) => record.spanContext().spanId));
+        // A span that already ended, in this batch or not (even one a wrapping processor filtered),
+        // is no longer running, so its placeholder is not sent.
+        for (const placeholder of placeholders)
+            if (!ended.has(placeholder.record.parentSpanContext?.spanId ?? "") &&
+                !this.transport.placeholderSettled(placeholder.record))
+                real.push(placeholder);
+        return real;
+    }
     async exportRecords(records) {
         const accepted = [];
+        // Placeholders are advisory: losing one is a warning, never an export failure.
+        const placeholders = new Set();
         const cache = new WeakMap();
         let failed = false;
         let redactedBytes = 0;
+        const invalid = (placeholder, message) => {
+            if (placeholder)
+                this.transport.issue(this.signal, "warning", 1, `${message} (in-progress span placeholder)`);
+            else {
+                failed = true;
+                this.transport.issue(this.signal, "invalid", 1, message);
+            }
+        };
+        const send = async (batch) => {
+            const count = batch.filter((record) => placeholders.has(record)).length;
+            if (!(await this.send(batch, count)))
+                failed = true;
+        };
         const resourceDeadline = Date.now() + this.transport.options.timeoutMillis;
-        for (const record of records) {
+        for (const { record, markers } of this.ordered(records)) {
             try {
                 const ready = record.resource.waitForAsyncAttributes?.();
                 if (ready) {
@@ -368,17 +514,30 @@ class ReportingExporter {
                         clearTimeout(timer);
                     }
                 }
-                const redacted = this.redact(record, cache);
+                let redacted = this.redact(record, cache);
+                // Added after redaction, so a redactor cannot alter the markers or the parent identity.
+                if (markers)
+                    redacted = {
+                        ...redacted,
+                        attributes: { ...redacted.attributes, ...markers },
+                    };
+                else if (this.signal === "traces") {
+                    const attributes = redacted.attributes;
+                    const kept = withoutPlaceholderMarkers(attributes);
+                    if (kept !== attributes)
+                        redacted = { ...redacted, attributes: kept };
+                }
                 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);
+                if (markers)
+                    placeholders.add(redacted);
             }
             catch {
-                failed = true;
-                this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be redacted or exceeds supported content limits");
+                invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits");
             }
         }
         // Each record is encoded once to measure it; a request is encoded once more when it is sent.
@@ -394,37 +553,41 @@ class ReportingExporter {
                 recordBytes = this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
             }
             catch {
-                failed = true;
-                this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be serialized");
+                invalid(placeholders.has(record), "Telemetry record could not be serialized");
                 continue;
             }
             const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
             if (batch.length && batchBytes + framedBytes > limit) {
-                if (!(await this.send(batch)))
-                    failed = true;
+                await send(batch);
                 batch = [];
                 batchBytes = 0;
             }
             if (recordBytes > limit) {
-                failed = true;
-                this.transport.issue(this.signal, "invalid", 1, "Telemetry record exceeds the 1 MiB request limit");
+                invalid(placeholders.has(record), "Telemetry record exceeds the 1 MiB request limit");
                 continue;
             }
             batch.push(record);
             batchBytes += framedBytes;
         }
-        if (batch.length && !(await this.send(batch)))
-            failed = true;
+        if (batch.length)
+            await send(batch);
         if (failed)
             throw new Error("Hue telemetry export failed");
     }
-    async send(records) {
+    /** Sends one request; `placeholders` of `records` are advisory and never count as lost. */
+    async send(records, placeholders = 0) {
         const options = this.transport.options;
+        const real = records.length - placeholders;
+        // A loss involving only placeholders is a warning. Mixed losses count only real records.
+        const lose = (message, status) => {
+            this.transport.issue(this.signal, real ? "failed" : "warning", real || placeholders, real ? message : `${message} (in-progress span placeholders only)`, status);
+            return !real;
+        };
         let rejected = 0;
         let validResponse = true;
         let receivedResponse = false;
+        let acceptsPlaceholders = false;
         let expired = false;
-        const agents = new Set();
         const deadline = Date.now() + options.timeoutMillis;
         let timer;
         const serializer = {
@@ -439,17 +602,27 @@ class ReportingExporter {
                     const count = Number(partial?.[this.signal === "traces" ? "rejectedSpans" : "rejectedLogRecords"] ?? 0);
                     if (!Number.isSafeInteger(count) || count < 0 || count > records.length)
                         throw new Error("Invalid rejection count");
-                    rejected = count;
-                    if (count || partial?.errorMessage)
-                        this.transport.issue(this.signal, count ? "rejected" : "warning", count, count
+                    // A receiver that accepts placeholders never rejects them for being placeholders, so its
+                    // rejections count as before. One without the header predates them and rejects each.
+                    const downgrade = placeholders > 0 && !acceptsPlaceholders;
+                    const placeholderRejections = downgrade ? Math.min(count, placeholders) : 0;
+                    if (downgrade)
+                        this.transport.rejectPlaceholders(placeholderRejections);
+                    const remaining = count - placeholderRejections;
+                    // Rejections are not matched to records. Attribute them to real records first.
+                    rejected = Math.min(remaining, real);
+                    if (remaining || (partial?.errorMessage && !downgrade))
+                        this.transport.issue(this.signal, rejected ? "rejected" : "warning", rejected || remaining, rejected
                             ? "Hue rejected telemetry records; inspect the project ingestion settings and supported limits"
-                            : "Hue returned an ingestion warning");
+                            : remaining
+                                ? "Hue rejected in-progress span placeholders"
+                                : "Hue returned an ingestion warning");
                     // Do not pass backend error text or raw response bytes into the global OTel diagnostic logger.
                     return {};
                 }
                 catch {
                     validResponse = false;
-                    this.transport.issue(this.signal, "failed", records.length, "Hue returned an invalid OTLP acknowledgement; acceptance is uncertain");
+                    lose("Hue returned an invalid OTLP acknowledgement; acceptance is uncertain");
                     return {};
                 }
             },
@@ -457,64 +630,44 @@ class ReportingExporter {
         const endpoint = `${options.baseUrl}/api/v1/otlp/v1/${this.signal}`;
         // Explicit configuration only. OTEL_EXPORTER_OTLP_* environment variables are meant
         // for generic exporters; merging them here could send another vendor's headers to Hue.
-        const delegate = createOtlpHttpExportDelegate({
-            url: endpoint,
-            headers: async () => ({
-                "Content-Type": "application/x-protobuf",
-                Authorization: `Bearer ${options.apiKey}`,
-            }),
-            // The transport prefixes this to OpenTelemetry's own User-Agent token.
-            userAgent: `hue-sdk-typescript/${sdkVersion}`,
-            timeoutMillis: options.timeoutMillis,
-            concurrencyLimit: 1,
-            compression: CompressionAlgorithm.GZIP,
-            agentFactory: 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;
-            },
-        }, serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
+        const transport = new OtlpHttpTransport(endpoint, {
+            "Content-Type": "application/x-protobuf",
+            Authorization: `Bearer ${options.apiKey}`,
+            "User-Agent": `hue-sdk-typescript/${sdkVersion} ${OTEL_USER_AGENT}`,
+        }, (headers) => {
+            acceptsPlaceholders = headers[PLACEHOLDERS_HEADER] === "1";
+        });
+        const delegate = createOtlpNetworkExportDelegate({ timeoutMillis: options.timeoutMillis, concurrencyLimit: 1, compression: "gzip" }, serializer, createOtlpHttpExporterMetrics(this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, endpoint, undefined), transport);
         const exporter = new OTLPExporterBase(delegate);
         try {
             const result = await new Promise((resolve) => {
                 timer = setTimeout(() => {
                     expired = true;
-                    for (const agent of agents)
-                        agent.destroy();
+                    transport.abort();
                     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 (!receivedResponse)
+                    return lose("Hue response ended without a complete OTLP acknowledgement; acceptance is uncertain");
                 if (validResponse)
-                    this.transport.acceptedRecords(this.signal, records.length - rejected);
-                return validResponse;
+                    this.transport.acceptedRecords(this.signal, real - rejected);
+                return validResponse || !real;
             }
             else {
                 const status = result.error instanceof OTLPExporterError && Number.isInteger(result.error.code)
                     ? result.error.code
                     : undefined;
-                this.transport.issue(this.signal, "failed", records.length, "Hue telemetry request failed", status);
-                return false;
+                return lose("Hue telemetry request failed", status);
             }
         }
         catch {
-            this.transport.issue(this.signal, "failed", records.length, "Hue telemetry request failed");
-            return false;
+            return lose("Hue telemetry request failed");
         }
         finally {
             clearTimeout(timer);
-            for (const agent of agents)
-                agent.destroy();
+            transport.abort();
             // 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(() => { });
@@ -527,6 +680,182 @@ class ReportingExporter {
         await this.forceFlush();
     }
 }
+// OpenTelemetry's OTLP/HTTP transport rules (otlp-exporter-base 0.222), restated because that
+// transport discards response headers, which Hue uses to announce features.
+const MAX_RETRIES = 5;
+const INITIAL_BACKOFF_MILLIS = 1000;
+const MAX_BACKOFF_MILLIS = 5000;
+const BACKOFF_MULTIPLIER = 1.5;
+const JITTER = 0.2;
+const MAX_RESPONSE_BYTES = 4 * 1024 * 1024;
+const RETRYABLE_STATUS = new Set([429, 502, 503, 504]);
+const RETRYABLE_NETWORK_ERRORS = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "EPIPE",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "ENOTFOUND",
+    "ENETUNREACH",
+    "EHOSTUNREACH",
+]);
+/** OpenTelemetry's exporter token, which follows Hue's in the User-Agent as it always has. */
+const OTEL_USER_AGENT = "OTel-OTLP-Exporter-JavaScript/0.222.0";
+function retryAfterMillis(value) {
+    if (value == null)
+        return undefined;
+    const seconds = Number.parseInt(value, 10);
+    if (Number.isInteger(seconds))
+        return seconds > 0 ? seconds * 1000 : -1;
+    const delay = new Date(value).getTime() - Date.now();
+    return delay >= 0 ? delay : 0;
+}
+function networkFailure(error) {
+    const code = error.code;
+    return typeof code === "string" && RETRYABLE_NETWORK_ERRORS.has(code)
+        ? { status: "retryable", error }
+        : { status: "failure", error };
+}
+function compress(data) {
+    return new Promise((resolve, reject) => gzip(data, (error, result) => (error ? reject(error) : resolve(result))));
+}
+/**
+ * Gzip-compressed OTLP/HTTP POSTs that never follow redirects, retried like OpenTelemetry's
+ * exporter within the request budget. `onSuccess` receives the headers of the 2xx response whose
+ * body becomes the acknowledgement, before that body is decoded. One instance serves a single
+ * export request: its connections are never reused, and `abort()` closes them at the export
+ * deadline.
+ */
+class OtlpHttpTransport {
+    url;
+    headers;
+    onSuccess;
+    // Requests in flight and how to settle each, so an abort never leaves an attempt pending.
+    requests = new Map();
+    agent;
+    aborted = false;
+    constructor(url, headers, onSuccess) {
+        this.url = url;
+        this.headers = headers;
+        this.onSuccess = onSuccess;
+    }
+    async send(data, timeoutMillis) {
+        const deadline = Date.now() + timeoutMillis;
+        let backoff = INITIAL_BACKOFF_MILLIS;
+        let result = await this.attempt(data, timeoutMillis);
+        for (let retries = MAX_RETRIES; result.status === "retryable" && retries > 0; retries--) {
+            const jitter = Math.random() * 2 * JITTER - JITTER;
+            const wait = result.retryInMillis ?? Math.max(Math.min(backoff * (1 + jitter), MAX_BACKOFF_MILLIS), 0);
+            backoff *= BACKOFF_MULTIPLIER;
+            // Return when the next attempt would start after the export deadline.
+            if (this.aborted || wait > deadline - Date.now())
+                return result;
+            await new Promise((resolve) => setTimeout(resolve, Math.max(0, wait)));
+            result = await this.attempt(data, Math.max(1, deadline - Date.now()));
+        }
+        return result;
+    }
+    async attempt(data, timeoutMillis) {
+        try {
+            if (this.aborted)
+                throw new Error("Hue export deadline exceeded");
+            const url = new URL(this.url);
+            const protocol = url.protocol;
+            // Loaded on first use, as OpenTelemetry's exporter does, so importing Hue never loads http
+            // before the application's http instrumentation can patch it.
+            const [{ Agent: ConnectionAgent, request }, body] = await Promise.all([
+                import(protocol === "https:" ? "node:https" : "node:http"),
+                compress(data),
+            ]);
+            if (this.aborted)
+                throw new Error("Hue export deadline exceeded");
+            // Never kept alive: each attempt's socket closes with its response or at the deadline.
+            this.agent ??= new ConnectionAgent({ keepAlive: false });
+            return await new Promise((resolve) => {
+                const req = request(url, {
+                    method: "POST",
+                    agent: this.agent,
+                    headers: {
+                        ...this.headers,
+                        "Content-Encoding": "gzip",
+                        "Content-Length": body.byteLength,
+                    },
+                }, (res) => {
+                    const chunks = [];
+                    let size = 0;
+                    const status = res.statusCode ?? 0;
+                    const success = status >= 200 && status <= 299;
+                    res.on("data", (chunk) => {
+                        size += chunk.length;
+                        if (size > MAX_RESPONSE_BYTES) {
+                            // Oversized responses fail regardless of status; resolve before tearing down.
+                            resolve({ status: "failure", error: new Error("OTLP response exceeded 4 MiB") });
+                            res.destroy();
+                            return;
+                        }
+                        chunks.push(chunk);
+                    });
+                    res.on("end", () => {
+                        if (success) {
+                            this.onSuccess(res.headers);
+                            resolve({ status: "success", data: Buffer.concat(chunks) });
+                        }
+                        else if (RETRYABLE_STATUS.has(status))
+                            resolve({
+                                status: "retryable",
+                                retryInMillis: retryAfterMillis(res.headers["retry-after"]),
+                            });
+                        else
+                            resolve({
+                                status: "failure",
+                                error: new OTLPExporterError(res.statusMessage, status, Buffer.concat(chunks).toString()),
+                            });
+                    });
+                    res.on("error", (error) => {
+                        // Sent, but the acknowledgement was not read: success without a body to decode.
+                        if (success)
+                            resolve({ status: "success" });
+                        else if (RETRYABLE_STATUS.has(status))
+                            resolve({
+                                status: "retryable",
+                                error,
+                                retryInMillis: retryAfterMillis(res.headers["retry-after"]),
+                            });
+                        else
+                            resolve({ status: "failure", error });
+                    });
+                });
+                this.requests.set(req, resolve);
+                req.on("close", () => this.requests.delete(req));
+                req.setTimeout(timeoutMillis, () => {
+                    req.destroy();
+                    resolve({ status: "retryable", error: new Error("Request timed out") });
+                });
+                req.on("error", (error) => resolve(networkFailure(error)));
+                req.end(body);
+            });
+        }
+        catch (error) {
+            return {
+                status: "failure",
+                error: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    }
+    /** Fails and destroys requests in flight and their sockets, and every later attempt. */
+    abort() {
+        this.aborted = true;
+        for (const [req, settle] of this.requests) {
+            settle({ status: "failure", error: new Error("Hue export deadline exceeded") });
+            req.destroy();
+        }
+        this.requests.clear();
+        this.agent?.destroy();
+    }
+    shutdown() {
+        this.abort();
+    }
+}
 /**
  * Creates the export pipeline for attach mode; pass it with the application's providers to
  * {@link createHue}. Validates options like an owned client.

package/dist/types.d.ts

@@ -43,6 +43,12 @@ export interface SharedHueOptions {
     timeoutMillis?: number;
     /** Aggregate estimated retained telemetry bytes across both signals, including in-flight work. Default 8 MiB. */
     maxQueueBytes?: number;
+    /**
+     * Announces AI and Hue spans that are still running with in-progress placeholder spans, so Hue
+     * shows a trace while it runs. Default `true`; always off for setup credentials (`hue_setup_…`),
+     * and turned off for the client when its receiver does not accept placeholders.
+     */
+    liveSpans?: boolean;
 }
 /**
  * Options for a client that owns its OpenTelemetry providers. An enabled client needs a project
@@ -75,7 +81,7 @@ export interface ExportIssue {
     signal: Signal;
     /** `rejected` by Hue, `failed` to deliver, `dropped` from the queue, `invalid` record or capture, or a non-failing `warning`. */
     kind: "rejected" | "failed" | "dropped" | "invalid" | "warning";
-    /** Records affected; zero for warnings and capture failures. */
+    /** Records affected; zero for capture failures and for warnings other than lost in-progress span placeholders. */
     count: number;
     /** HTTP status when the issue came from a response. */
     status?: number;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export declare const sdkVersion = "0.5.1";
+export declare const sdkVersion = "0.7.0";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/write-version.mjs from package.json; do not edit by hand.
 /** Package version shared by the instrumentation scope and the export User-Agent. */
-export const sdkVersion = "0.5.1";
+export const sdkVersion = "0.7.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hue-run/sdk",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "private": false,
   "license": "MIT",
   "publishConfig": {