@hue-run/sdk 0.18.2 → 0.19.1

package/dist/transport.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { gzip } from "node:zlib";
 import { ExportResultCode } from "@opentelemetry/core";
 import { createOtlpNetworkExportDelegate, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
@@ -6,7 +7,7 @@ import { LogsExporterMetricsHelper, ProtobufLogsSerializer, ProtobufTraceSeriali
 import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace";
 import { BatchLogRecordProcessor, } from "@opentelemetry/sdk-logs";
 import { isInsecureOrigin, REDACTION_CONTEXT_UNITS, validateOptions } from "./config.js";
-import { BLOBS_KEY, MAX_BLOB_ENTRIES, blobEntry, countFallback, BlobUploader, FALLBACK_MESSAGES, fallbackAttributes, fallbackRecord, heldBytesOf, MAX_HELD_BLOB_BYTES, newTally, mediaKey, offloadAttributes, offloadRecord, sizeOf, uploadBudgetMillis, } from "./blobs.js";
+import { BLOBS_KEY, MAX_BLOB_ENTRIES, blobEntry, countFallback, BlobUploader, FALLBACK_MESSAGES, fallbackAttributes, fallbackRecord, heldBytesOf, LATE_FALLBACK_MESSAGES, MAX_HELD_BLOB_BYTES, mergeWhenSettled, newTally, mediaKey, offloadAttributes, offloadRecord, sizeOf, uploadBudgetMillis, } from "./blobs.js";
 import { isByteSource } from "./large-media.js";
 import { advertisedLimits, BATCH_TARGET_BYTES, DEFAULT_RECEIVER_LIMITS, fitsWithoutCompression, } from "./limits.js";
 import { announcesLiveSpan, LIVE_SPAN_INTERVAL_MILLIS, MAX_LIVE_SPANS, pendingPlaceholder, PLACEHOLDERS_HEADER, withoutPlaceholderMarkers, } from "./live-spans.js";
@@ -109,9 +110,11 @@ function mediaEntry(file) {
  * them, reported like any refused request.
  */
 export const MAX_RATE_LIMIT_HOLD_MILLIS = 60_000;
-/** How long one export may take with requests of `timeoutMillis` each: its uploads of values over
+/** How long one export may take with requests of `timeoutMillis` each: hashing its values over
  * the inline limit, its requests, and a hold for a rate-limited receiver on top. Processors and
- * providers wait this long for a drain. */
+ * providers wait this long for a drain. A drain also waits for the uploads its exports queued,
+ * which run beside the requests and end within six timeouts and a minute of being queued, so they
+ * fit within the same budget. */
 export function exportBudgetMillis(timeoutMillis) {
     return uploadBudgetMillis(timeoutMillis) + timeoutMillis * 16 + 1000 + MAX_RATE_LIMIT_HOLD_MILLIS;
 }
@@ -195,7 +198,11 @@ export class HueTransport {
     logExporter;
     closed = false;
     shutdownPromise;
-    flushPromise;
+    /** The latest flush's send of its records; the next flush's send starts after it. */
+    sendPromise;
+    /** Set while a flush sends its records: the processors leave the uploads to that flush, which
+     * waits for them after its send, so no flush's send waits behind another's uploads. */
+    sendingRecords = new AsyncLocalStorage();
     // Open spans not yet announced. Each is considered once, at the next tick after it starts.
     live = new Set();
     liveTimer;
@@ -226,6 +233,10 @@ export class HueTransport {
     /** Bytes of values over the inline limit queued spans hold whole for upload, and each span's. */
     heldBytes = 0;
     held = new WeakMap();
+    /** Bytes of each record's charge (its own held values and its staged files) that its queued
+     * uploads took over before the record was finished: charged to the uploads alone until they
+     * settle or the record is finished. */
+    heldByUploads = new WeakMap();
     mediaMemo = new MediaDigestMemo();
     // Context identity also matches safe API wrappers to the provider's ended span. Abandoned
     // spans retain no span objects, and share the 2048-span / 128 MiB holding bounds.
@@ -242,6 +253,11 @@ export class HueTransport {
     });
     uploaded = 0;
     uploadFallbacks = 0;
+    /** Each export's queued uploads, until they all settle and are reported. */
+    uploadReports = new Set();
+    /** Settles once every upload report registered so far has: each drain awaits this one promise,
+     * so a drain costs the same however many uploads are pending. */
+    uploadsSettled = Promise.resolve();
     constructor(options) {
         this.options = validateOptions(options);
         Object.defineProperty(this, "options", { enumerable: false });
@@ -333,10 +349,25 @@ export class HueTransport {
                     this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record", undefined, traceIdsOf([span]));
                 }
             },
-            forceFlush: () => spans.forceFlush(),
-            shutdown: () => {
+            // The spans are sent first, then the uploads queued so far are waited for, unless a
+            // flush sends them: that flush waits for the uploads after its send.
+            forceFlush: async () => {
+                try {
+                    await spans.forceFlush();
+                }
+                finally {
+                    if (!this.sendingRecords.getStore())
+                        await this.drainUploads();
+                }
+            },
+            shutdown: async () => {
                 this.stopLiveSpans();
-                return spans.shutdown();
+                try {
+                    await spans.shutdown();
+                }
+                finally {
+                    await this.drainUploads();
+                }
             },
         };
         this.logRecordProcessor = {
@@ -367,8 +398,23 @@ export class HueTransport {
                     this.issue("logs", "invalid", 1, "Telemetry processor could not accept a record", undefined, traceIdsOf([log]));
                 }
             },
-            forceFlush: () => logs.forceFlush(),
-            shutdown: () => logs.shutdown(),
+            forceFlush: async () => {
+                try {
+                    await logs.forceFlush();
+                }
+                finally {
+                    if (!this.sendingRecords.getStore())
+                        await this.drainUploads();
+                }
+            },
+            shutdown: async () => {
+                try {
+                    await logs.shutdown();
+                }
+                finally {
+                    await this.drainUploads();
+                }
+            },
         };
     }
     /**
@@ -400,8 +446,8 @@ export class HueTransport {
             const hold = !advisory && this.holdsValues()
                 ? {
                     valueBytes: this.limits.valueBytes,
-                    budget: Math.max(0, MAX_HELD_BLOB_BYTES - this.heldBytes),
-                    first: this.heldBytes === 0,
+                    budget: this.heldRoom(),
+                    first: this.heldBytes === 0 && !this.uploader?.pendingBytes(),
                 }
                 : undefined;
             const snapshot = signal === "traces"
@@ -534,6 +580,12 @@ export class HueTransport {
                 this.heldBytes -= held;
                 this.held.delete(record);
             }
+            // Released whole above: the part its uploads took over stays charged to them.
+            const taken = this.heldByUploads.get(record);
+            if (taken) {
+                this.heldBytes += taken;
+                this.heldByUploads.delete(record);
+            }
         }
     }
     /** @internal The same bounded digest memo is used by explicit and inline media. */
@@ -560,7 +612,7 @@ export class HueTransport {
         const files = this.media.get(identity) ?? [];
         if (files.length >= 64 ||
             (!this.media.has(identity) && this.media.size >= 2048) ||
-            this.heldBytes + heldBytesOf(file.bytes) > MAX_HELD_BLOB_BYTES) {
+            heldBytesOf(file.bytes) > this.heldRoom()) {
             this.uploadFallbacks++;
             this.issue("traces", "warning", 1, "File bytes did not fit the SDK's upload budget; their hue.file metadata was recorded", undefined, [span.spanContext().traceId]);
             return false;
@@ -610,7 +662,7 @@ export class HueTransport {
             const staged = this.media.get(identity) ?? [];
             if (staged.length >= MAX_BLOB_ENTRIES ||
                 (!this.media.has(identity) && this.media.size >= 2048) ||
-                this.heldBytes + heldBytesOf(file.bytes) > MAX_HELD_BLOB_BYTES) {
+                heldBytesOf(file.bytes) > this.heldRoom()) {
                 countFallback(tally, "budget", traceId);
                 continue;
             }
@@ -662,7 +714,7 @@ export class HueTransport {
             return;
         this.logParts.delete(body);
         const size = pending.files.reduce((total, file) => total + heldBytesOf(file.bytes), 0);
-        if (this.heldBytes + size > MAX_HELD_BLOB_BYTES) {
+        if (size > this.heldRoom()) {
             const tally = newTally();
             for (const _file of pending.files)
                 countFallback(tally, "budget", pending.traceId);
@@ -673,6 +725,44 @@ export class HueTransport {
         this.heldBytes += size;
         this.held.set(queued, (this.held.get(queued) ?? 0) + size);
     }
+    /** What the held-value budget has room for: values queued records hold and bytes unsettled
+     * uploads hold share it. */
+    heldRoom() {
+        return Math.max(0, MAX_HELD_BLOB_BYTES - this.heldBytes - (this.uploader?.pendingBytes() ?? 0));
+    }
+    /** An upload `record`'s export queued, as it is queued: flushes and the processors wait for it
+     * from now on, and the `shared` bytes it holds of the record's own are charged to the upload
+     * alone, so the held-value budget never counts them twice while the export goes on. A charge
+     * `released` before the record is finished is handed back to the record, which still holds
+     * them. */
+    uploadQueued(record, settled, shared, released) {
+        this.awaitUploads(settled);
+        const identity = this.mediaIdentity(record);
+        const staged = identity
+            ? (this.media.get(identity) ?? []).reduce((total, file) => total + heldBytesOf(file.bytes), 0)
+            : 0;
+        const taken = this.heldByUploads.get(record) ?? 0;
+        const moved = Math.min(shared, (this.held.get(record) ?? 0) + staged - taken);
+        if (moved <= 0)
+            return;
+        this.heldBytes -= moved;
+        this.heldByUploads.set(record, taken + moved);
+        // Held weakly: a pending upload never keeps its finished record alive.
+        const queued = new WeakRef(record);
+        const handBack = () => {
+            const owner = queued.deref();
+            const still = owner && this.heldByUploads.get(owner);
+            if (!owner || !still)
+                return;
+            const back = Math.min(moved, still);
+            this.heldBytes += back;
+            if (still > back)
+                this.heldByUploads.set(owner, still - back);
+            else
+                this.heldByUploads.delete(owner);
+        };
+        void released.then(handBack, handBack);
+    }
     /** Registers a span whose staged files are released if it is never exported. */
     ownMedia(span, identity) {
         if (this.mediaOwners.has(identity))
@@ -763,11 +853,19 @@ export class HueTransport {
         return this.offloadsValues() && this.uploader?.available() === true;
     }
     /** @internal Exporter callback: a redacted span with the values its redaction left to the
-     * upload step placed: uploaded and listed under `hue.blobs`, or cut as before. Never rejects. */
-    async offloadSpan(span, collector, upload, tally) {
+     * upload step placed: listed under `hue.blobs` with their uploads queued (each added to `late`
+     * once it settles, and charged in place of the `queued` record it came from), or cut as before.
+     * Never rejects. */
+    async offloadSpan(span, collector, upload, tally, late, queued) {
         // A record without a readable context cannot name its trace: its values are cut.
         const traceId = recordTraceId(span);
         const valueBytes = this.limits.valueBytes;
+        // A record placed as a fallback counts its values there: its queued uploads are not added.
+        const own = {
+            tally: newTally(),
+            settled: [],
+            queued: (settled, shared, released) => this.uploadQueued(queued, settled, shared, released),
+        };
         try {
             if (!this.uploader)
                 throw new Error("Uploads are unavailable");
@@ -778,7 +876,10 @@ export class HueTransport {
                 upload,
                 tally,
                 memo: this.mediaMemo,
+                background: own,
             });
+            if (own.settled.length)
+                late.settled.push(mergeWhenSettled(late.tally, own.tally, own.settled));
             return { ...span, attributes: attributes };
         }
         catch {
@@ -789,10 +890,11 @@ export class HueTransport {
         }
     }
     /** @internal Exporter callback: a redacted log record with the media its redaction left to
-     * the upload step placed: its attributes' and its body's files uploaded and listed under its own
-     * `hue.blobs` (keys `<attribute>#<pointer>`, `body#<pointer>`), under the log record's trace;
-     * a file not uploaded keeps its bytes inline, and the record is cut as before. Never rejects. */
-    async offloadLog(log, collector, upload, tally) {
+     * the upload step placed: its attributes' and its body's files listed under its own `hue.blobs`
+     * (keys `<attribute>#<pointer>`, `body#<pointer>`) with their uploads queued under the log
+     * record's trace (charged in place of the `queued` record); a file refused keeps its bytes
+     * inline, and the record is cut as before. Never rejects. */
+    async offloadLog(log, collector, upload, tally, late, queued) {
         const traceId = log.spanContext?.traceId ?? "";
         const valueBytes = this.limits.valueBytes;
         const placed = (result) => ({
@@ -800,29 +902,39 @@ export class HueTransport {
             attributes: result.attributes,
             ...(collector.body ? { body: result.body } : {}),
         });
+        const own = {
+            tally: newTally(),
+            settled: [],
+            queued: (settled, shared, released) => this.uploadQueued(queued, settled, shared, released),
+        };
         try {
             if (!this.uploader)
                 throw new Error("Uploads are unavailable");
-            return placed(await offloadRecord(log.attributes, collector, {
+            const result = await offloadRecord(log.attributes, collector, {
                 uploader: this.uploader,
                 traceId,
                 valueBytes,
                 upload,
                 tally,
                 memo: this.mediaMemo,
-            }));
+                background: own,
+            });
+            if (own.settled.length)
+                late.settled.push(mergeWhenSettled(late.tally, own.tally, own.settled));
+            return placed(result);
         }
         catch {
             return placed(fallbackRecord(log.attributes, collector, valueBytes, tally, traceId, this.mediaMemo));
         }
     }
     /** @internal Exporter callback: counts an export's uploads and reports each kind of fallback
-     * once, as a warning naming its traces: the values were exported, cut as before. */
-    reportOffload(tally, signal = "traces") {
+     * once, as a warning naming its traces: the values were exported cut as before, or, `late`,
+     * their uploads failed after their records listed them. */
+    reportOffload(tally, signal = "traces", late = false) {
         this.uploaded += tally.uploaded;
         for (const [reason, { count, traceIds }] of tally.fallbacks) {
             this.uploadFallbacks += count;
-            this.issue(signal, "warning", count, FALLBACK_MESSAGES[reason], undefined, traceIds.size && traceIds.size <= MAX_ISSUE_TRACE_IDS ? [...traceIds] : undefined);
+            this.issue(signal, "warning", count, (late ? LATE_FALLBACK_MESSAGES : FALLBACK_MESSAGES)[reason], undefined, traceIds.size && traceIds.size <= MAX_ISSUE_TRACE_IDS ? [...traceIds] : undefined);
         }
     }
     /** @internal Exporter callback: counts records the collector acknowledged. */
@@ -890,8 +1002,9 @@ export class HueTransport {
     }
     /** @internal Ends every rate-limit hold now and refuses new ones, once a shutdown's caller has
      * stopped waiting: the held records are reported lost to the rate limit, and no timer of theirs
-     * keeps the process running for the receiver's `Retry-After`. Uploads in flight end too, and no
-     * other starts: their values are exported cut, as before uploads existed. */
+     * keeps the process running for the receiver's `Retry-After`. Queued and in-flight uploads end
+     * too, and no other starts: their records' entries stay and the uploads count as failed, and
+     * values not yet exported are exported cut, as before uploads existed. */
     releaseRateLimitHolds() {
         this.holdsReleased = true;
         for (const release of [...this.holds])
@@ -1015,27 +1128,67 @@ export class HueTransport {
             this.endedSpans.delete(this.endedSpans.keys().next().value);
     }
     /**
-     * Waits for the processors' and exporters' in-flight work; drain the providers first.
+     * Waits for the processors' and exporters' in-flight work, then for the uploads their exports
+     * queued; drain the providers first. Only the sends are serialized: a flush sends its records
+     * once an earlier flush sent its own, never after that flush's uploads.
      *
      * @throws HueExportError when a new non-warning issue was recorded since the previous observation.
      */
     flush() {
+        return this.flushRecords().report;
+    }
+    /**
+     * @internal A flush in two steps: its send settles `sent`, then it waits on its own for the
+     * uploads queued so far and settles `report` as {@link flush} does. `providers` (the client's
+     * provider flush) runs first, before the flush joins the transport's sends, so a hung borrowed
+     * provider never holds up the transport's own flushes. `sent` waits for it, though, and the
+     * client starts each flush once the previous one's `sent` settles: it holds up the client's
+     * later flushes.
+     */
+    flushRecords(providers) {
         const from = this.observedSequence;
-        const next = (this.flushPromise ?? Promise.resolve()).then(() => this.flushOnce(from), () => this.flushOnce(from));
-        this.flushPromise = next;
+        const join = () => this.sendRecords();
+        const sent = providers ? this.sendingRecords.run(true, providers).then(join, join) : join();
+        const report = sent.then(async (processors) => {
+            // Exports the processors did not start (a timer's, still in flight) queued uploads too.
+            await this.drainUploads();
+            return this.flushReport(from, processors);
+        });
+        return { sent, report };
+    }
+    /** Sends what the processors and exporters hold, once the previous flush's send ended. */
+    sendRecords() {
+        const send = () => this.sendingRecords.run(true, async () => {
+            const processors = await Promise.allSettled([
+                this.spanProcessor.forceFlush(),
+                this.logRecordProcessor.forceFlush(),
+            ]);
+            await Promise.all([this.traceExporter.forceFlush(), this.logExporter.forceFlush()]);
+            return processors;
+        });
+        const sent = (this.sendPromise ?? Promise.resolve()).then(send, send);
+        this.sendPromise = sent;
         const clear = () => {
-            if (this.flushPromise === next)
-                this.flushPromise = undefined;
+            if (this.sendPromise === sent)
+                this.sendPromise = undefined;
         };
-        void next.then(clear, clear);
-        return next;
-    }
-    async flushOnce(from) {
-        const processors = await Promise.allSettled([
-            this.spanProcessor.forceFlush(),
-            this.logRecordProcessor.forceFlush(),
-        ]);
-        await Promise.all([this.traceExporter.forceFlush(), this.logExporter.forceFlush()]);
+        void sent.then(clear, clear);
+        return sent;
+    }
+    /** @internal Exporter callback: an export's queued uploads, reported once they all settle. */
+    awaitUploads(report) {
+        // Never an unhandled rejection, whatever the report does.
+        const tracked = report.catch(() => { });
+        this.uploadReports.add(tracked);
+        void tracked.then(() => this.uploadReports.delete(tracked));
+        const earlier = this.uploadsSettled;
+        this.uploadsSettled = tracked.then(() => earlier);
+    }
+    /** Waits for the uploads queued so far; each ends within its lifetime, so this is bounded. */
+    drainUploads() {
+        return this.uploadsSettled;
+    }
+    flushReport(from, processors) {
         for (const [index, result] of processors.entries())
             if (result.status === "rejected") {
                 const signal = index === 0 ? "traces" : "logs";
@@ -1050,8 +1203,9 @@ export class HueTransport {
         return report;
     }
     /**
-     * Flushes and stops the processors; records emitted afterwards are dropped and counted. In attach
-     * mode call it after shutting down the application's providers.
+     * Flushes and stops the processors, waits for queued uploads, then ends the uploader; records
+     * emitted afterwards are dropped and counted. In attach mode call it after shutting down the
+     * application's providers.
      *
      * @throws HueExportError when the final flush observed new failures.
      */
@@ -1067,7 +1221,10 @@ export class HueTransport {
                     this.logRecordProcessor.shutdown(),
                 ]);
                 await Promise.allSettled([this.traceExporter.forceFlush(), this.logExporter.forceFlush()]);
+                await this.drainUploads();
                 this.uploader?.close();
+                // The reports of uploads the close ended land before shutdown resolves.
+                await this.drainUploads();
                 for (const identity of this.media.keys())
                     this.releaseMediaIdentity(identity);
                 this.logParts.clear();
@@ -1266,7 +1423,24 @@ class ReportingExporter {
                 real.push(placeholder);
         return real;
     }
+    /** Places and sends the records; the uploads their placement queued are reported once they
+     * settle, after the records were sent, never awaited here. */
     async exportRecords(records) {
+        const late = { tally: newTally(), settled: [] };
+        try {
+            await this.placeAndSend(records, late);
+        }
+        finally {
+            if (late.settled.length)
+                this.reportWhenSettled(late);
+        }
+    }
+    /** Reports an export's uploads once they all settle. Built apart from the export, so a pending
+     * upload never keeps the export's records alive. */
+    reportWhenSettled(late) {
+        this.transport.awaitUploads(Promise.all(late.settled).then(() => this.transport.reportOffload(late.tally, this.signal, true)));
+    }
+    async placeAndSend(records, late) {
         // Completed records and placeholders travel in separate requests, completed records first,
         // so a rejection count is always one kind of record's. Placeholders are advisory: losing one
         // is a warning, never an export failure.
@@ -1288,21 +1462,17 @@ class ReportingExporter {
             }
         };
         const resourceDeadline = Date.now() + this.transport.options.timeoutMillis;
-        // How long this export has held its records for a rate-limited receiver, its value uploads'
-        // waits included.
+        // How long this export has held its records for a rate-limited receiver.
         const hold = { millis: 0 };
-        // A span's values over the inline limit are uploaded before it is measured, within the
-        // export's upload budget; a placeholder's never are.
+        // A span's values over the inline limit are hashed and placed before it is measured, within
+        // the export's hashing deadline; their uploads are queued, never awaited, and a placeholder's
+        // values never upload.
         const upload = {
             deadline: Date.now() + uploadBudgetMillis(this.transport.options.timeoutMillis),
-            wait: async (millis) => {
-                if (hold.millis + millis > MAX_RATE_LIMIT_HOLD_MILLIS)
-                    return false;
-                hold.millis += millis;
-                return this.transport.holdForRateLimit(millis);
-            },
+            wait: async () => false,
         };
         const tally = newTally();
+        // Each record's attachments to upload once it is fitted, with the queued record holding them.
         const helpers = new Map();
         const placed = [];
         for (const { record, markers } of this.ordered(records)) {
@@ -1351,8 +1521,8 @@ class ReportingExporter {
                         offload.body ||
                         offload.attachments?.length)
                     ? this.signal === "traces"
-                        ? this.transport.offloadSpan(redacted, offload, upload, tally)
-                        : this.transport.offloadLog(redacted, offload, upload, tally)
+                        ? this.transport.offloadSpan(redacted, offload, upload, tally, late, record)
+                        : this.transport.offloadLog(redacted, offload, upload, tally, late, record)
                     : undefined;
                 placed.push({
                     record,
@@ -1403,7 +1573,7 @@ class ReportingExporter {
                                 [BLOBS_KEY]: [...baseline, ...retained.map(mediaEntry)],
                             },
                         };
-                        helpers.set(redacted, { files: retained, baseline });
+                        helpers.set(redacted, { files: retained, baseline, source: record });
                     }
                 }
                 const bytes = 512 +
@@ -1605,7 +1775,11 @@ class ReportingExporter {
                             else
                                 delete attributes[BLOBS_KEY];
                         }
-                        attachments = { record: { ...fittedRecord, attributes }, files };
+                        attachments = {
+                            record: { ...fittedRecord, attributes },
+                            files,
+                            source: helper.source,
+                        };
                         remaining = [];
                     }
                 }
@@ -1623,15 +1797,17 @@ class ReportingExporter {
                 }
                 admitted.push({ fitted, attachments });
             }
-            // Decide every event/reference admission before starting helper uploads. The shared
-            // uploader's four workers place files across spans under the same upload deadline.
+            // Decide every event/reference admission before queueing helper uploads: a file fitting
+            // removed is never uploaded. Their entries are written again as the fitted record listed
+            // them, and the files upload after the records are sent.
             const placed = await Promise.all(admitted.map(async ({ fitted, attachments }) => {
                 if (!attachments)
                     return fitted;
                 try {
-                    const uploaded = await this.transport.offloadSpan(attachments.record, { candidates: [], cut: [], attachments: attachments.files }, upload, tally);
+                    const uploaded = await this.transport.offloadSpan(attachments.record, { candidates: [], cut: [], attachments: attachments.files }, upload, tally, late, attachments.source);
                     measured.delete(fitted.record);
-                    // Actual references can differ when an existing object supplies its media type.
+                    // The entries name each file's own type, as the fitted record's did; a file refused
+                    // when queued leaves its entry out, so the record is measured again, cheaply.
                     const final = await probe(uploaded);
                     if (final?.request)
                         measured.set(final.record, final.request);
@@ -1644,8 +1820,9 @@ class ReportingExporter {
                     return undefined;
                 }
             }));
-            // Preparation includes explicit file uploads. Report their outcome once, before delivery
-            // failures can consume the diagnostic callback's rate-limit slot. Placeholders never upload.
+            // Values refused when their records were placed are reported once, before delivery failures
+            // can consume the diagnostic callback's rate-limit slot; queued uploads are reported once
+            // they settle. Placeholders never upload.
             if (!advisory)
                 this.transport.reportOffload(tally, this.signal);
             let batch = [];

package/dist/types.d.ts

@@ -136,11 +136,13 @@ export interface ExportReport {
     instrumentationFailures: number;
     /** Whole span attributes, inline media, attachments and opted-in file helper uploads stored
      * apart from their records (or already held by Hue), each listed under the record's
-     * `hue.blobs`. */
+     * `hue.blobs`; counted when the upload completes, which can be after the export that listed
+     * it. */
     uploadedValues: number;
     /** Whole-attribute, inline-media, attachment and opted-in file helper uploads that could not be
-     * attached. Content falls back to truncation, media digests, or file metadata, with a warning
-     * issue. */
+     * attached, each with a warning issue: values exported in their fallback form (truncation,
+     * media digests, or file metadata), and values whose upload failed after their record was
+     * exported (their `hue.blobs` entries stay). */
     uploadFallbacks: number;
 }
 /** Caller budget for {@link HueClient.flushSafe} and {@link HueClient.shutdownSafe}. */

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.18.2";
+export declare const sdkVersion = "0.19.1";

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.18.2";
+export const sdkVersion = "0.19.1";

package/package.json

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