@hue-run/sdk 0.17.0 → 0.18.1

package/dist/transport.js

@@ -6,20 +6,75 @@ 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, 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, 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";
-/** Each surviving event authorizes one staged request, including repeated digests. */
-function survivingMedia(files, span, tally) {
+/** 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 = span.spanContext().traceId;
+    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) => {
-        const index = span.events.findIndex((event, index) => !consumed.has(index) &&
+        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])) &&
@@ -31,7 +86,7 @@ function survivingMedia(files, span, tally) {
             return [];
         }
         consumed.add(index);
-        const name = span.events[index].attributes?.["hue.file.name"];
+        const name = events[index].attributes?.["hue.file.name"];
         return [
             {
                 bytes: file.bytes,
@@ -44,7 +99,7 @@ function survivingMedia(files, span, tally) {
     });
 }
 function mediaEntry(file) {
-    return blobEntry(`event:hue.file:${file.digest.sha256}`, file.digest.sha256, file.digest.size, file.contentType, file.name);
+    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)
@@ -129,6 +184,9 @@ export class HueTransport {
      * over the request limit), reported on the trace's root span as `hue.sdk.dropped_records` when
      * the root is exported, so Hue reads the trace as incomplete by that many records. */
     droppedByTrace = new Map();
+    /** Whether a trace's root carries `hue.sdk.dropped_records`; off for a replay of recorded
+     * spans, which must send the same root on every run. */
+    marksDroppedRecords = true;
     instrumentationFailures = 0;
     diagnosticPending = false;
     lastDiagnosticAt = -Infinity;
@@ -169,6 +227,10 @@ export class HueTransport {
     // 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 }) => {
@@ -193,9 +255,10 @@ export class HueTransport {
                 ...(offload ? { offload } : {}),
             });
         });
-        this.logExporter = new ReportingExporter(this, "logs", ProtobufLogsSerializer, LogsExporterMetricsHelper, (log, cache) => redactLog(log, this.options, cache, {
+        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({
@@ -275,9 +338,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 {
@@ -316,7 +391,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),
@@ -325,7 +400,7 @@ export class HueTransport {
                 : undefined;
             const snapshot = signal === "traces"
                 ? snapshotSpan(record, remaining, this.options.captureContent, valueUnits, hold, this.mediaMemo)
-                : snapshotLog(record, remaining, this.options.captureContent, valueUnits);
+                : 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)
@@ -442,6 +517,7 @@ export class HueTransport {
     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);
@@ -484,19 +560,122 @@ export class HueTransport {
         const bytes = Uint8Array.from(file.bytes);
         files.push({ ...file, bytes });
         this.media.set(identity, files);
-        if (!this.mediaOwners.has(identity)) {
-            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();
-            }
-        }
+        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;
@@ -552,8 +731,11 @@ export class HueTransport {
             }
         }
     }
-    /** @internal Staged requests are matched against surviving events before upload. */
+    /** @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) ?? []) : [];
     }
@@ -573,13 +755,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)
@@ -601,13 +778,41 @@ 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) {
+        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. */
@@ -620,13 +825,20 @@ export class HueTransport {
      * (`consumeDroppedRecords`): a root written again under retry says the same, and a root whose
      * request failed has not told Hue, so its count is not forgotten with it. */
     withDroppedRecords(span) {
-        if (span.parentSpanContext)
+        if (span.parentSpanContext || !this.marksDroppedRecords)
             return span;
         const count = this.droppedByTrace.get(span.spanContext().traceId);
         if (!count)
             return span;
         return { ...span, attributes: { ...span.attributes, [DROPPED_RECORDS_KEY]: count } };
     }
+    /** @internal For an import that replays recorded spans: roots never carry the count of
+     * records this run did not deliver, so a later run that delivers them sends each root as it
+     * was first sent, which Hue keeps as an exact replay. The losses are still counted and
+     * reported. */
+    omitDroppedRecords() {
+        this.marksDroppedRecords = false;
+    }
     /** @internal Exporter callback: these counts reached Hue on their traces' roots. Only what a
      * root carried is forgotten: a record lost while its request was in flight is still counted. */
     consumeDroppedRecords(counts) {
@@ -848,6 +1060,7 @@ export class HueTransport {
                 this.uploader?.close();
                 for (const identity of this.media.keys())
                     this.releaseMediaIdentity(identity);
+                this.logParts.clear();
                 this.mediaMemo.clear();
             }
         })();
@@ -988,6 +1201,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;
@@ -1095,27 +1312,50 @@ 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);
-                const files = 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.signal === "traces" && this.transport.offloadsValues()) {
+                if (!markers && this.transport.offloadsValues()) {
                     const files = this.transport.mediaAttachments(record);
                     for (let index = 0; index < files.length; index++)
-                        countFallback(tally, "budget", record.spanContext().traceId);
+                        countFallback(tally, "budget", recordTraceId(record));
                 }
                 invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits", record);
             }
@@ -1137,20 +1377,19 @@ class ReportingExporter {
                         redacted = { ...redacted, attributes: kept };
                 }
                 if (files.length) {
-                    const span = redacted;
-                    const listed = span.attributes[BLOBS_KEY];
+                    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", span.spanContext().traceId);
+                        countFallback(tally, "budget", recordTraceId(redacted));
                     if (retained.length) {
-                        // Fit the event and its reference together before sending customer bytes.
+                        // Fit the event or part and its reference together before sending customer bytes.
                         redacted = {
                             ...redacted,
                             attributes: {
-                                ...span.attributes,
+                                ...redacted.attributes,
                                 [BLOBS_KEY]: [...baseline, ...retained.map(mediaEntry)],
                             },
                         };
@@ -1166,7 +1405,7 @@ class ReportingExporter {
             }
             catch {
                 for (let index = 0; index < retained.length; index++)
-                    countFallback(tally, "budget", record.spanContext().traceId);
+                    countFallback(tally, "budget", recordTraceId(record));
                 invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits", record);
             }
         }
@@ -1331,15 +1570,16 @@ class ReportingExporter {
                 try {
                     fitted = await fit(record);
                     if (fitted && helper) {
-                        const span = fitted.record;
-                        const matched = survivingMedia(remaining, span, tally);
+                        const fittedRecord = fitted.record;
+                        const traceId = recordTraceId(fittedRecord);
+                        const matched = survivingMedia(remaining, fittedRecord, tally, record);
                         remaining = matched;
-                        const listed = span.attributes[BLOBS_KEY];
+                        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", span.spanContext().traceId);
+                                countFallback(tally, "budget", traceId);
                                 return false;
                             }
                             entries.splice(index, 1);
@@ -1347,7 +1587,7 @@ class ReportingExporter {
                         });
                         remaining = files;
                         // Drop provisional entries, retaining only the original references after fitting.
-                        const attributes = { ...span.attributes };
+                        const attributes = { ...fittedRecord.attributes };
                         if (Array.isArray(listed)) {
                             const baseline = listed.slice(0, helper.baseline.length);
                             if (baseline.length)
@@ -1355,19 +1595,19 @@ class ReportingExporter {
                             else
                                 delete attributes[BLOBS_KEY];
                         }
-                        attachments = { span: { ...span, attributes }, files };
+                        attachments = { record: { ...fittedRecord, attributes }, files };
                         remaining = [];
                     }
                 }
                 catch {
                     for (let index = 0; index < remaining.length; index++)
-                        countFallback(tally, "budget", record.spanContext().traceId);
+                        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", record.spanContext().traceId);
+                        countFallback(tally, "budget", recordTraceId(record));
                     invalid(advisory, OVER_REQUEST_LIMIT, record);
                     continue;
                 }
@@ -1379,7 +1619,7 @@ class ReportingExporter {
                 if (!attachments)
                     return fitted;
                 try {
-                    const uploaded = await this.transport.offloadSpan(attachments.span, { candidates: [], cut: [], attachments: attachments.files }, upload, tally);
+                    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);
@@ -1397,7 +1637,7 @@ class ReportingExporter {
             // 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.transport.reportOffload(tally, this.signal);
             let batch = [];
             let batchBytes = 0;
             for (const fitted of placed) {

package/dist/types.d.ts

@@ -1,5 +1,7 @@
 import type { Attributes, Context, Span, SpanKind, Tracer, TracerProvider } from "@opentelemetry/api";
+import type { AttributeValue } from "@opentelemetry/api";
 import type { LoggerProvider } from "@opentelemetry/api-logs";
+import type { Attachment } from "./attachment.js";
 /**
  * JSON-compatible data: the shape content has on the wire after the helpers encode it. Helpers
  * accept `unknown` and validate at runtime; values that are not plain JSON are omitted with an
@@ -8,6 +10,14 @@ import type { LoggerProvider } from "@opentelemetry/api-logs";
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
 };
+/**
+ * JSON data that may hold an {@link Attachment} anywhere: what a span attribute passed to a helper
+ * may be besides an OpenTelemetry attribute value. Such a value is recorded as JSON text with each
+ * attachment as its digest part.
+ */
+export type AttachmentJson = Attachment | JsonValue | AttachmentJson[] | {
+    [key: string]: AttachmentJson;
+};
 /** Telemetry signal named by export reports, issues and processors. */
 export type Signal = "traces" | "logs";
 /** Options accepted by every Hue client and transport, whether enabled or disabled. */
@@ -124,11 +134,13 @@ export interface ExportReport {
     pendingBytes: number;
     /** Helper capture or instrumentation failures that omitted telemetry while preserving application results. */
     instrumentationFailures: number;
-    /** Whole span attributes, inline media, and opted-in file helper uploads stored apart from
-     * their spans (or already held by Hue), each listed under the span's `hue.blobs`. */
+    /** 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`. */
     uploadedValues: number;
-    /** Whole-attribute, inline-media, 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. */
+    /** 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. */
     uploadFallbacks: number;
 }
 /** Caller budget for {@link HueClient.flushSafe} and {@link HueClient.shutdownSafe}. */
@@ -149,8 +161,15 @@ export interface SafeLifecycleResult {
 export interface SpanOptions {
     /** OpenTelemetry span kind; `INTERNAL` by default. */
     kind?: SpanKind;
-    /** Attributes set when the span starts. */
-    attributes?: Attributes;
+    /**
+     * Attributes set when the span starts. A value that is a JSON object, an array OpenTelemetry
+     * cannot hold (not of one primitive type) or an {@link Attachment} is recorded as JSON text, with
+     * each attachment as its digest part and its bytes uploaded; put files under `metadata` for Hue to
+     * list them as the span's metadata files.
+     */
+    attributes?: {
+        [key: string]: AttributeValue | AttachmentJson | undefined;
+    };
     /** Recorded as `gen_ai.conversation.id` on this span and inherited by nested helper spans. */
     sessionId?: string;
     /** Recorded as `user.id` on this span and inherited by nested helper spans. */

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.17.0";
+export declare const sdkVersion = "0.18.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.17.0";
+export const sdkVersion = "0.18.1";

package/package.json

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