@hue-run/sdk 0.16.0 → 0.18.0

package/dist/transport.js

@@ -6,13 +6,101 @@ 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 { BlobUploader, FALLBACK_MESSAGES, fallbackAttributes, MAX_HELD_BLOB_BYTES, newTally, offloadAttributes, uploadBudgetMillis, } from "./blobs.js";
+import { BLOBS_KEY, MAX_BLOB_ENTRIES, blobEntry, countFallback, BlobUploader, FALLBACK_MESSAGES, fallbackAttributes, fallbackRecord, MAX_HELD_BLOB_BYTES, newTally, mediaKey, offloadAttributes, offloadRecord, uploadBudgetMillis, } from "./blobs.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";
-import { estimateRecordBytes } from "./safety.js";
+import { estimateRecordBytes, spanSource } from "./safety.js";
+import { MediaDigestMemo, isMediaName } from "./inline-files.js";
+import { locateParts } from "./attachment.js";
 import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { DROPPED_RECORDS_KEY, isContentKey, isTruncatedMarker, redactLog, redactSpan, TRUNCATED_KEY, truncatedMarker, withTruncatedKeys, } from "./privacy.js";
 import { sdkVersion } from "./version.js";
+/** A record's trace: a span's context, a log record's span identifiers; "" when unreadable. */
+function recordTraceId(record) {
+    try {
+        return "spanContext" in record && typeof record.spanContext === "function"
+            ? record.spanContext().traceId
+            : (record.spanContext?.traceId ?? "");
+    }
+    catch {
+        return "";
+    }
+}
+/** The value of a record's attribute, or a log record's body, that holds placed attachments. */
+function placedValue(record, attribute) {
+    if (attribute === "body" &&
+        !("spanContext" in record && typeof record.spanContext === "function"))
+        return record.body;
+    return record.attributes[attribute];
+}
+/**
+ * The staged files a record still authorizes. Each surviving `hue.file` event authorizes one
+ * staged request, including repeated digests. An attachment placed in a value is authorized by
+ * its own part in the value as exported: after redaction (`before` absent) each part is found in
+ * its value, and keyed at its pointer there, a part the redactor removed taking its upload with
+ * it; after fitting (`before`, the record as it was fitted) a part survives while fitting left its
+ * value as it was.
+ */
+function survivingMedia(files, record, tally, before) {
+    const consumed = new Set();
+    const traceId = recordTraceId(record);
+    const events = "events" in record ? record.events : [];
+    const located = new Map();
+    const locate = (attribute) => {
+        let parts = located.get(attribute);
+        if (parts)
+            return [];
+        let value = placedValue(record, attribute);
+        try {
+            if (typeof value === "string")
+                value = JSON.parse(value);
+        }
+        catch {
+            value = undefined;
+        }
+        parts = locateParts(value, files.filter((file) => file.attribute === attribute)).map(({ file, pointer, name }) => {
+            const { name: _staged, ...rest } = file;
+            return { ...rest, key: `${attribute}#${pointer}`, ...(name ? { name } : {}) };
+        });
+        located.set(attribute, parts);
+        return parts;
+    };
+    return files.flatMap((file) => {
+        if (file.attribute !== undefined) {
+            if (!before)
+                return locate(file.attribute);
+            if (placedValue(record, file.attribute) === placedValue(before, file.attribute))
+                return [file];
+            countFallback(tally, "budget", traceId);
+            return [];
+        }
+        const index = events.findIndex((event, index) => !consumed.has(index) &&
+            event.name === "hue.file" &&
+            (!file.eventTime ||
+                (event.time[0] === file.eventTime[0] && event.time[1] === file.eventTime[1])) &&
+            event.attributes?.["hue.file.sha256"] === file.digest.sha256 &&
+            event.attributes?.["hue.file.size"] === file.digest.size &&
+            event.attributes?.["hue.file.media_type"] === file.contentType);
+        if (index < 0) {
+            countFallback(tally, "budget", traceId);
+            return [];
+        }
+        consumed.add(index);
+        const name = events[index].attributes?.["hue.file.name"];
+        return [
+            {
+                bytes: file.bytes,
+                digest: file.digest,
+                contentType: file.contentType,
+                ...(file.eventTime ? { eventTime: file.eventTime } : {}),
+                ...(isMediaName(name) ? { name } : {}),
+            },
+        ];
+    });
+}
+function mediaEntry(file) {
+    return blobEntry(mediaKey(file), file.digest.sha256, file.digest.size, file.contentType, file.name);
+}
 /**
  * How long one export holds its records for a receiver that refused them for their rate (HTTP 429)
  * and asked to be retried later than a request's deadline allows: the records stay queued, counted
@@ -125,11 +213,27 @@ export class HueTransport {
     admissionCuts = new WeakMap();
     // The span's own messages whose large inline files each admitted span shrank to their digest.
     admissionDigests = new WeakMap();
+    // The span's own messages each admitted span inspected, or left to export to inspect.
+    admissionInspected = new WeakMap();
     /** Uploads values over the inline limit apart from their spans; absent when disabled. */
     uploader;
     /** Bytes of values over the inline limit queued spans hold whole for upload, and each span's. */
     heldBytes = 0;
     held = 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.
+    media = new Map();
+    // Attachments placed in a log record's body, from `emit` until the record is admitted, and
+    // the admitted records' own.
+    logParts = new Map();
+    logMedia = new WeakMap();
+    mediaOwners = new Map();
+    mediaTimer;
+    mediaFinalizer = new FinalizationRegistry(({ identity, token }) => {
+        if (this.mediaOwners.get(identity)?.token === token)
+            this.releaseMediaIdentity(identity);
+    });
     uploaded = 0;
     uploadFallbacks = 0;
     constructor(options) {
@@ -137,15 +241,21 @@ export class HueTransport {
         Object.defineProperty(this, "options", { enumerable: false });
         this.liveSpans = this.options.enabled !== false && this.options.liveSpans;
         this.announcesLiveSpans = this.liveSpans;
-        this.traceExporter = new ReportingExporter(this, "traces", ProtobufTraceSerializer, TraceExporterMetricsHelper, (span, cache, offload) => redactSpan(span, this.options, cache, {
-            valueBytes: this.limits.valueBytes,
-            cut: this.admissionCuts.get(span),
-            digested: this.admissionDigests.get(span),
-            ...(offload ? { offload } : {}),
-        }));
-        this.logExporter = new ReportingExporter(this, "logs", ProtobufLogsSerializer, LogsExporterMetricsHelper, (log, cache) => redactLog(log, this.options, cache, {
+        this.traceExporter = new ReportingExporter(this, "traces", ProtobufTraceSerializer, TraceExporterMetricsHelper, (span, cache, offload) => {
+            // Export inspects only the messages admission inspected within the record's allowance.
+            if (offload)
+                offload.inspected = this.admissionInspected.get(span);
+            return redactSpan(span, this.options, cache, {
+                valueBytes: this.limits.valueBytes,
+                cut: this.admissionCuts.get(span),
+                digested: this.admissionDigests.get(span),
+                ...(offload ? { offload } : {}),
+            });
+        });
+        this.logExporter = new ReportingExporter(this, "logs", ProtobufLogsSerializer, LogsExporterMetricsHelper, (log, cache, offload) => redactLog(log, this.options, cache, {
             valueBytes: this.limits.valueBytes,
             cut: this.admissionCuts.get(log),
+            ...(offload ? { offload } : {}),
         }));
         if (this.options.enabled !== false)
             this.uploader = new BlobUploader({
@@ -187,18 +297,30 @@ export class HueTransport {
                     this.stopLiveTimer();
                 let admitted;
                 try {
-                    if (!(span.spanContext().traceFlags & 1))
+                    if (!(span.spanContext().traceFlags & 1)) {
+                        this.releaseMedia(span);
                         return;
+                    }
                     const queued = this.enqueue("traces", span);
-                    if (!queued)
+                    if (!queued) {
+                        const tally = newTally();
+                        for (const file of this.mediaAttachments(span))
+                            if (file.bytes.byteLength)
+                                countFallback(tally, "budget", span.spanContext().traceId);
+                        this.reportOffload(tally);
+                        this.releaseMedia(span);
                         return;
+                    }
                     admitted = queued;
+                    this.protectMedia(admitted);
                     this.countEnded(admitted);
                     spans.onEnd(admitted);
                 }
                 catch {
                     if (admitted)
                         this.finish("traces", [admitted]);
+                    else
+                        this.releaseMedia(span);
                     this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record", undefined, traceIdsOf([span]));
                 }
             },
@@ -213,9 +335,21 @@ export class HueTransport {
                 let admitted;
                 try {
                     const queued = this.enqueue("logs", log);
-                    if (!queued)
+                    if (!queued) {
+                        const pending = log.body !== null && typeof log.body === "object"
+                            ? this.logParts.get(log.body)
+                            : undefined;
+                        if (pending) {
+                            const tally = newTally();
+                            for (const _file of pending.files)
+                                countFallback(tally, "budget", pending.traceId);
+                            this.reportOffload(tally, "logs");
+                            this.logParts.delete(log.body);
+                        }
                         return;
+                    }
                     admitted = queued;
+                    this.admitLogParts(log, queued);
                     logs.onEmit(queued);
                 }
                 catch {
@@ -254,7 +388,7 @@ export class HueTransport {
             // and its full size could drop the record before that cut ever ran. A span's own value
             // that export may upload is held whole instead, within the held-value budget.
             const valueUnits = this.limits.valueBytes + REDACTION_CONTEXT_UNITS;
-            const hold = signal === "traces" && !advisory && this.holdsValues()
+            const hold = !advisory && this.holdsValues()
                 ? {
                     valueBytes: this.limits.valueBytes,
                     budget: Math.max(0, MAX_HELD_BLOB_BYTES - this.heldBytes),
@@ -262,12 +396,14 @@ export class HueTransport {
                 }
                 : undefined;
             const snapshot = signal === "traces"
-                ? snapshotSpan(record, remaining, this.options.captureContent, valueUnits, hold)
-                : snapshotLog(record, remaining, this.options.captureContent, valueUnits);
+                ? snapshotSpan(record, remaining, this.options.captureContent, valueUnits, hold, this.mediaMemo)
+                : snapshotLog(record, remaining, this.options.captureContent, valueUnits, hold, this.mediaMemo);
             if (snapshot.cut.size)
                 this.admissionCuts.set(snapshot.record, snapshot.cut);
             if (snapshot.digested.size)
                 this.admissionDigests.set(snapshot.record, snapshot.digested);
+            if (signal === "traces")
+                this.admissionInspected.set(snapshot.record, snapshot.inspected);
             if (snapshot.held) {
                 this.heldBytes += snapshot.held;
                 this.held.set(snapshot.record, snapshot.held);
@@ -311,7 +447,11 @@ export class HueTransport {
             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)
+                if (span.ended) {
+                    this.releaseMedia(span);
+                    continue;
+                }
+                if (!this.liveSpans || !this.batchSpans)
                     continue;
                 const { record, markers } = pendingPlaceholder(span);
                 const admitted = this.enqueue("traces", record, true);
@@ -373,6 +513,8 @@ export class HueTransport {
     /** @internal Exporter callback: releases queued records after an export attempt settles. */
     finish(signal, records) {
         for (const record of records) {
+            this.releaseMedia(record);
+            this.logMedia.delete(record);
             const pending = signal === "traces" ? this.spans : this.logs;
             this.pendingBytes -= pending.get(record) ?? 0;
             pending.delete(record);
@@ -383,7 +525,218 @@ export class HueTransport {
             }
         }
     }
-    /** @internal Whether spans' values over the inline limit are uploaded: content is captured and
+    /** @internal The same bounded digest memo is used by explicit and inline media. */
+    digestMedia(bytes, traceId) {
+        return this.mediaMemo.bytes(bytes, traceId);
+    }
+    /** @internal Retain a defensive copy within the existing held-value budget. */
+    stageMedia(span, file) {
+        if (this.closed || !this.offloadsValues() || file?.bytes.byteLength === 0)
+            return true;
+        if (!file) {
+            const tally = newTally();
+            countFallback(tally, "budget", span.spanContext().traceId);
+            this.reportOffload(tally);
+            return false;
+        }
+        if (!this.holdsValues()) {
+            this.uploadFallbacks++;
+            this.issue("traces", "warning", 1, "File bytes could not be uploaded while the upload service was unavailable; their hue.file metadata was recorded", undefined, [span.spanContext().traceId]);
+            return false;
+        }
+        const identity = this.mediaIdentity(span);
+        this.sweepMedia();
+        const files = this.media.get(identity) ?? [];
+        if (files.length >= 64 ||
+            (!this.media.has(identity) && this.media.size >= 2048) ||
+            this.heldBytes + file.bytes.byteLength > MAX_HELD_BLOB_BYTES) {
+            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;
+        }
+        const bytes = Uint8Array.from(file.bytes);
+        files.push({ ...file, bytes });
+        this.media.set(identity, files);
+        this.ownMedia(span, identity);
+        this.heldBytes += bytes.byteLength;
+        return true;
+    }
+    /**
+     * @internal Stages the attachments placed in a span's `attribute`, replacing those an earlier
+     * value of the attribute placed: each is uploaded at export when its part survives there. A
+     * file that cannot be held is counted as not uploaded; it keeps its digest part.
+     */
+    stageParts(span, attribute, files) {
+        if (this.closed || !this.offloadsValues())
+            return;
+        const traceId = span.spanContext().traceId;
+        const identity = this.mediaIdentity(span);
+        const previous = this.media.get(identity);
+        if (previous?.some((file) => file.attribute === attribute)) {
+            const kept = previous.filter((file) => {
+                if (file.attribute !== attribute)
+                    return true;
+                this.heldBytes -= file.bytes.byteLength;
+                return false;
+            });
+            if (kept.length)
+                this.media.set(identity, kept);
+            else
+                this.media.delete(identity);
+        }
+        const tally = newTally();
+        for (const file of files) {
+            if (!file.bytes.byteLength)
+                continue;
+            const refused = this.uploader?.refusal();
+            if (!this.holdsValues() || refused) {
+                countFallback(tally, refused ?? "unsupported", traceId);
+                continue;
+            }
+            this.sweepMedia();
+            const staged = this.media.get(identity) ?? [];
+            if (staged.length >= MAX_BLOB_ENTRIES ||
+                (!this.media.has(identity) && this.media.size >= 2048) ||
+                this.heldBytes + file.bytes.byteLength > MAX_HELD_BLOB_BYTES) {
+                countFallback(tally, "budget", traceId);
+                continue;
+            }
+            // Attachment bytes are the attachment's own copy: held as they are.
+            staged.push({ ...file, attribute });
+            this.media.set(identity, staged);
+            this.heldBytes += file.bytes.byteLength;
+            this.ownMedia(span, identity);
+        }
+        if (tally.fallbacks.size)
+            this.reportOffload(tally);
+    }
+    /**
+     * @internal Stages the attachments placed in a log record's body until the record is emitted
+     * (`body` is the object passed to `emit`); {@link unstageLogParts} drops what no processor of
+     * this transport admitted.
+     */
+    stageLogParts(body, traceId, files) {
+        if (this.closed || !this.offloadsValues())
+            return;
+        const tally = newTally();
+        const staged = [];
+        for (const file of files) {
+            if (!file.bytes.byteLength)
+                continue;
+            const refused = this.uploader?.refusal();
+            if (!this.holdsValues() || refused)
+                countFallback(tally, refused ?? "unsupported", traceId);
+            else if (staged.length >= MAX_BLOB_ENTRIES)
+                countFallback(tally, "budget", traceId);
+            else
+                staged.push({ ...file, attribute: "body" });
+        }
+        if (tally.fallbacks.size)
+            this.reportOffload(tally, "logs");
+        if (staged.length)
+            this.logParts.set(body, { traceId, files: staged });
+    }
+    /** @internal Drops a log record's staged attachments once it was emitted. */
+    unstageLogParts(body) {
+        this.logParts.delete(body);
+    }
+    /** Holds the staged attachments of a log record being admitted with the queued record, within
+     * the held-value budget; those the budget refuses are counted as not uploaded. */
+    admitLogParts(log, queued) {
+        const body = log.body;
+        const pending = body !== null && typeof body === "object" ? this.logParts.get(body) : undefined;
+        if (!pending)
+            return;
+        this.logParts.delete(body);
+        const size = pending.files.reduce((total, file) => total + file.bytes.byteLength, 0);
+        if (this.heldBytes + size > MAX_HELD_BLOB_BYTES) {
+            const tally = newTally();
+            for (const _file of pending.files)
+                countFallback(tally, "budget", pending.traceId);
+            this.reportOffload(tally, "logs");
+            return;
+        }
+        this.logMedia.set(queued, pending.files);
+        this.heldBytes += size;
+        this.held.set(queued, (this.held.get(queued) ?? 0) + size);
+    }
+    /** Registers a span whose staged files are released if it is never exported. */
+    ownMedia(span, identity) {
+        if (this.mediaOwners.has(identity))
+            return;
+        const source = spanSource(span);
+        const token = {};
+        this.mediaOwners.set(identity, { source: new WeakRef(source), token });
+        this.mediaFinalizer.register(source, { identity, token }, token);
+        if (!this.mediaTimer) {
+            this.mediaTimer = setInterval(() => this.sweepMedia(), LIVE_SPAN_INTERVAL_MILLIS);
+            this.mediaTimer.unref();
+        }
+    }
+    mediaIdentity(record) {
+        if (!("spanContext" in record) || typeof record.spanContext !== "function")
+            return undefined;
+        const { traceId, spanId } = record.spanContext();
+        return `${traceId}:${spanId}`;
+    }
+    releaseMedia(record) {
+        const identity = this.mediaIdentity(record);
+        if (!identity)
+            return;
+        this.releaseMediaIdentity(identity);
+    }
+    protectMedia(record) {
+        const identity = this.mediaIdentity(record);
+        if (!identity)
+            return;
+        const owner = this.mediaOwners.get(identity);
+        if (owner)
+            this.mediaFinalizer.unregister(owner.token);
+        this.mediaOwners.delete(identity);
+        if (!this.mediaOwners.size) {
+            clearInterval(this.mediaTimer);
+            this.mediaTimer = undefined;
+        }
+    }
+    releaseMediaIdentity(identity) {
+        const owner = this.mediaOwners.get(identity);
+        if (owner)
+            this.mediaFinalizer.unregister(owner.token);
+        this.mediaOwners.delete(identity);
+        if (!this.mediaOwners.size) {
+            clearInterval(this.mediaTimer);
+            this.mediaTimer = undefined;
+        }
+        const files = this.media.get(identity);
+        if (!files)
+            return;
+        for (const file of files)
+            this.heldBytes -= file.bytes.byteLength;
+        this.media.delete(identity);
+    }
+    sweepMedia() {
+        for (const [identity, owner] of this.mediaOwners) {
+            try {
+                const source = owner.source.deref();
+                if (!source ||
+                    source.ended === true ||
+                    source.isRecording?.() === false)
+                    this.releaseMediaIdentity(identity);
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    /** @internal Staged requests are matched against surviving events and parts before upload. */
+    mediaAttachments(record) {
+        const logged = this.logMedia.get(record);
+        if (logged)
+            return logged;
+        const identity = this.mediaIdentity(record);
+        return identity ? (this.media.get(identity) ?? []) : [];
+    }
+    /** @internal Whether spans' content and media may be uploaded: content is captured and
      * the key is a project key (setup credentials send metadata only). A value that then cannot be
      * uploaded is cut, reported and counted. */
     offloadsValues() {
@@ -391,7 +744,7 @@ export class HueTransport {
             this.options.captureContent &&
             !this.options.apiKey.startsWith("hue_setup_"));
     }
-    /** @internal Whether values over the inline limit are worth holding whole for upload now: they
+    /** @internal Whether content and media are worth holding whole for upload now: they
      * are uploaded, and the receiver has not shown it lacks the upload route. */
     holdsValues() {
         return this.offloadsValues() && this.uploader?.available() === true;
@@ -399,13 +752,8 @@ export class HueTransport {
     /** @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) {
-        let traceId = "";
-        try {
-            traceId = span.spanContext().traceId;
-        }
-        catch {
-            // A span without a readable context cannot name its trace: its values are cut.
-        }
+        // A record without a readable context cannot name its trace: its values are cut.
+        const traceId = recordTraceId(span);
         const valueBytes = this.limits.valueBytes;
         try {
             if (!this.uploader)
@@ -416,23 +764,52 @@ export class HueTransport {
                 valueBytes,
                 upload,
                 tally,
+                memo: this.mediaMemo,
             });
             return { ...span, attributes: attributes };
         }
         catch {
             return {
                 ...span,
-                attributes: fallbackAttributes(span.attributes, collector, valueBytes, tally, traceId),
+                attributes: fallbackAttributes(span.attributes, collector, valueBytes, tally, traceId, this.mediaMemo),
             };
         }
     }
+    /** @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) {
+        const traceId = log.spanContext?.traceId ?? "";
+        const valueBytes = this.limits.valueBytes;
+        const placed = (result) => ({
+            ...log,
+            attributes: result.attributes,
+            ...(collector.body ? { body: result.body } : {}),
+        });
+        try {
+            if (!this.uploader)
+                throw new Error("Uploads are unavailable");
+            return placed(await offloadRecord(log.attributes, collector, {
+                uploader: this.uploader,
+                traceId,
+                valueBytes,
+                upload,
+                tally,
+                memo: this.mediaMemo,
+            }));
+        }
+        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) {
+    reportOffload(tally, signal = "traces") {
         this.uploaded += tally.uploaded;
         for (const [reason, { count, traceIds }] of tally.fallbacks) {
             this.uploadFallbacks += count;
-            this.issue("traces", "warning", count, FALLBACK_MESSAGES[reason], undefined, traceIds.size && traceIds.size <= MAX_ISSUE_TRACE_IDS ? [...traceIds] : undefined);
+            this.issue(signal, "warning", count, FALLBACK_MESSAGES[reason], undefined, traceIds.size && traceIds.size <= MAX_ISSUE_TRACE_IDS ? [...traceIds] : undefined);
         }
     }
     /** @internal Exporter callback: counts records the collector acknowledged. */
@@ -669,6 +1046,12 @@ export class HueTransport {
                     this.spanProcessor.shutdown(),
                     this.logRecordProcessor.shutdown(),
                 ]);
+                await Promise.allSettled([this.traceExporter.forceFlush(), this.logExporter.forceFlush()]);
+                this.uploader?.close();
+                for (const identity of this.media.keys())
+                    this.releaseMediaIdentity(identity);
+                this.logParts.clear();
+                this.mediaMemo.clear();
             }
         })();
         return this.shutdownPromise;
@@ -808,6 +1191,10 @@ function shedContent(record, signal, shed) {
             : span.links,
     };
 }
+/** Whether a trace id can name an upload's trace: 32 lowercase hex digits, not all zero. */
+function isUploadTraceId(traceId) {
+    return typeof traceId === "string" && /^[0-9a-f]{32}$/.test(traceId) && !/^0+$/.test(traceId);
+}
 class ReportingExporter {
     transport;
     signal;
@@ -896,6 +1283,7 @@ class ReportingExporter {
             },
         };
         const tally = newTally();
+        const helpers = new Map();
         const placed = [];
         for (const { record, markers } of this.ordered(records)) {
             try {
@@ -914,23 +1302,56 @@ class ReportingExporter {
                         clearTimeout(timer);
                     }
                 }
-                const offload = !markers && this.signal === "traces" && this.transport.offloadsValues()
-                    ? { candidates: [], cut: [] }
+                const uploads = !markers && this.transport.offloadsValues();
+                // A log record's media upload under its own trace: one without a trace is not offered.
+                const offload = uploads &&
+                    (this.signal === "traces" ||
+                        isUploadTraceId(record.spanContext?.traceId))
+                    ? this.signal === "traces"
+                        ? { candidates: [], cut: [] }
+                        : { candidates: [], cut: [], log: true }
                     : undefined;
                 const redacted = this.redact(record, cache, offload);
+                let files = uploads
+                    ? survivingMedia(this.transport.mediaAttachments(record), redacted, tally)
+                    : [];
+                if (this.signal === "logs" && files.length) {
+                    // A log record's attachments upload with the media its body holds, in the one step
+                    // that places a log record's files; a record without a trace uploads none.
+                    if (offload)
+                        offload.attachments = files;
+                    else
+                        for (let index = 0; index < files.length; index++)
+                            countFallback(tally, "budget", recordTraceId(record));
+                    files = [];
+                }
+                const offloaded = offload &&
+                    (offload.candidates.length ||
+                        offload.cut.length ||
+                        offload.body ||
+                        offload.attachments?.length)
+                    ? this.signal === "traces"
+                        ? this.transport.offloadSpan(redacted, offload, upload, tally)
+                        : this.transport.offloadLog(redacted, offload, upload, tally)
+                    : undefined;
                 placed.push({
                     record,
+                    files,
                     ...(markers ? { markers } : {}),
-                    redacted: offload && (offload.candidates.length || offload.cut.length)
-                        ? this.transport.offloadSpan(redacted, offload, upload, tally)
-                        : redacted,
+                    redacted: offloaded ?? redacted,
                 });
             }
             catch {
+                if (!markers && this.transport.offloadsValues()) {
+                    const files = this.transport.mediaAttachments(record);
+                    for (let index = 0; index < files.length; index++)
+                        countFallback(tally, "budget", recordTraceId(record));
+                }
                 invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits", record);
             }
         }
-        for (const { record, markers, redacted: placing } of placed) {
+        for (const { record, markers, files, redacted: placing } of placed) {
+            let retained = files;
             try {
                 let redacted = await placing;
                 // Added after redaction, so a redactor cannot alter the markers or the parent identity.
@@ -945,6 +1366,26 @@ class ReportingExporter {
                     if (kept !== attributes)
                         redacted = { ...redacted, attributes: kept };
                 }
+                if (files.length) {
+                    const listed = redacted.attributes[BLOBS_KEY];
+                    const baseline = Array.isArray(listed)
+                        ? listed.filter((entry) => typeof entry === "string")
+                        : [];
+                    retained = files.slice(0, Math.max(0, MAX_BLOB_ENTRIES - baseline.length));
+                    for (let index = retained.length; index < files.length; index++)
+                        countFallback(tally, "budget", recordTraceId(redacted));
+                    if (retained.length) {
+                        // Fit the event or part and its reference together before sending customer bytes.
+                        redacted = {
+                            ...redacted,
+                            attributes: {
+                                ...redacted.attributes,
+                                [BLOBS_KEY]: [...baseline, ...retained.map(mediaEntry)],
+                            },
+                        };
+                        helpers.set(redacted, { files: retained, baseline });
+                    }
+                }
                 const bytes = 512 +
                     estimateRecordBytes(recordData(redacted, this.signal), this.transport.options.maxQueueBytes - redactedBytes);
                 if (redactedBytes + bytes > this.transport.options.maxQueueBytes)
@@ -953,6 +1394,8 @@ class ReportingExporter {
                 (markers ? pending : real).push(redacted);
             }
             catch {
+                for (let index = 0; index < retained.length; index++)
+                    countFallback(tally, "budget", recordTraceId(record));
                 invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits", record);
             }
         }
@@ -1036,7 +1479,6 @@ class ReportingExporter {
             // export may have adopted lower ones meanwhile, and each attempt checks them again.
             return fitsLimits(body, this.transport.receiverLimits()) ? body : undefined;
         };
-        this.transport.reportOffload(tally);
         /** Sends one kind of record (completed records, or placeholders alone: `advisory`) in one
          * request, or in halves when it is over the receiver's limits. A trace's root among completed
          * records carries the trace's dropped-record count as it stands when its request is made, so
@@ -1109,25 +1551,89 @@ class ReportingExporter {
         const pack = async (accepted, advisory) => {
             // Every record is measured, shed and, where it cannot be sent, counted lost before any root
             // is written, so a root carries the losses of children that ended after it.
-            const prepared = [];
+            const admitted = [];
             for (const record of accepted) {
                 let fitted;
+                let attachments;
+                const helper = helpers.get(record);
+                let remaining = helper?.files ?? [];
                 try {
                     fitted = await fit(record);
+                    if (fitted && helper) {
+                        const fittedRecord = fitted.record;
+                        const traceId = recordTraceId(fittedRecord);
+                        const matched = survivingMedia(remaining, fittedRecord, tally, record);
+                        remaining = matched;
+                        const listed = fittedRecord.attributes[BLOBS_KEY];
+                        const entries = Array.isArray(listed) ? [...listed] : [];
+                        const files = matched.filter((file) => {
+                            const index = entries.indexOf(mediaEntry(file), helper.baseline.length);
+                            if (index < 0) {
+                                countFallback(tally, "budget", traceId);
+                                return false;
+                            }
+                            entries.splice(index, 1);
+                            return true;
+                        });
+                        remaining = files;
+                        // Drop provisional entries, retaining only the original references after fitting.
+                        const attributes = { ...fittedRecord.attributes };
+                        if (Array.isArray(listed)) {
+                            const baseline = listed.slice(0, helper.baseline.length);
+                            if (baseline.length)
+                                attributes[BLOBS_KEY] = baseline;
+                            else
+                                delete attributes[BLOBS_KEY];
+                        }
+                        attachments = { record: { ...fittedRecord, attributes }, files };
+                        remaining = [];
+                    }
                 }
                 catch {
+                    for (let index = 0; index < remaining.length; index++)
+                        countFallback(tally, "budget", recordTraceId(record));
                     invalid(advisory, "Telemetry record could not be serialized", record);
                     continue;
                 }
                 if (!fitted) {
+                    for (let index = 0; index < remaining.length; index++)
+                        countFallback(tally, "budget", recordTraceId(record));
                     invalid(advisory, OVER_REQUEST_LIMIT, record);
                     continue;
                 }
-                prepared.push(fitted);
+                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.
+            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);
+                    measured.delete(fitted.record);
+                    // Actual references can differ when an existing object supplies its media type.
+                    const final = await probe(uploaded);
+                    if (final?.request)
+                        measured.set(final.record, final.request);
+                    if (!final)
+                        invalid(advisory, OVER_REQUEST_LIMIT, fitted.record);
+                    return final;
+                }
+                catch {
+                    invalid(advisory, "Telemetry record could not be serialized", fitted.record);
+                    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.
+            if (!advisory)
+                this.transport.reportOffload(tally, this.signal);
             let batch = [];
             let batchBytes = 0;
-            for (const { record, bytes: recordBytes } of prepared) {
+            for (const fitted of placed) {
+                if (!fitted)
+                    continue;
+                const { record, bytes: recordBytes } = fitted;
                 const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
                 const target = Math.min(this.transport.receiverLimits().decodedBytes, BATCH_TARGET_BYTES);
                 if (batch.length && batchBytes + framedBytes > target) {