@hue-run/sdk 0.18.0 → 0.18.2

package/dist/transport.js

@@ -6,7 +6,8 @@ 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, MAX_HELD_BLOB_BYTES, newTally, mediaKey, offloadAttributes, offloadRecord, uploadBudgetMillis, } from "./blobs.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 { 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";
 import { estimateRecordBytes, spanSource } from "./safety.js";
@@ -184,6 +185,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;
@@ -215,6 +219,8 @@ export class HueTransport {
     admissionDigests = new WeakMap();
     // The span's own messages each admitted span inspected, or left to export to inspect.
     admissionInspected = new WeakMap();
+    // The span's own values each admitted span held whole past the inspection bounds.
+    admissionLarge = 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. */
@@ -242,9 +248,12 @@ export class HueTransport {
         this.liveSpans = this.options.enabled !== false && this.options.liveSpans;
         this.announcesLiveSpans = this.liveSpans;
         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)
+            // Export inspects only the messages admission inspected within the record's allowance,
+            // and reads in place the values it held whole past the inspection bounds.
+            if (offload) {
                 offload.inspected = this.admissionInspected.get(span);
+                offload.large = this.admissionLarge.get(span);
+            }
             return redactSpan(span, this.options, cache, {
                 valueBytes: this.limits.valueBytes,
                 cut: this.admissionCuts.get(span),
@@ -305,7 +314,7 @@ export class HueTransport {
                     if (!queued) {
                         const tally = newTally();
                         for (const file of this.mediaAttachments(span))
-                            if (file.bytes.byteLength)
+                            if (sizeOf(file.bytes))
                                 countFallback(tally, "budget", span.spanContext().traceId);
                         this.reportOffload(tally);
                         this.releaseMedia(span);
@@ -404,6 +413,8 @@ export class HueTransport {
                 this.admissionDigests.set(snapshot.record, snapshot.digested);
             if (signal === "traces")
                 this.admissionInspected.set(snapshot.record, snapshot.inspected);
+            if (snapshot.large.size)
+                this.admissionLarge.set(snapshot.record, snapshot.large);
             if (snapshot.held) {
                 this.heldBytes += snapshot.held;
                 this.held.set(snapshot.record, snapshot.held);
@@ -531,7 +542,7 @@ export class HueTransport {
     }
     /** @internal Retain a defensive copy within the existing held-value budget. */
     stageMedia(span, file) {
-        if (this.closed || !this.offloadsValues() || file?.bytes.byteLength === 0)
+        if (this.closed || !this.offloadsValues() || (file && sizeOf(file.bytes) === 0))
             return true;
         if (!file) {
             const tally = newTally();
@@ -549,16 +560,18 @@ export class HueTransport {
         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.heldBytes + heldBytesOf(file.bytes) > 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);
+        // A file read from disk as it is uploaded holds no bytes; bytes are copied, so a later change
+        // to the caller's buffer cannot alter what was recorded.
+        const bytes = isByteSource(file.bytes) ? file.bytes : Uint8Array.from(file.bytes);
         files.push({ ...file, bytes });
         this.media.set(identity, files);
         this.ownMedia(span, identity);
-        this.heldBytes += bytes.byteLength;
+        this.heldBytes += heldBytesOf(bytes);
         return true;
     }
     /**
@@ -576,7 +589,7 @@ export class HueTransport {
             const kept = previous.filter((file) => {
                 if (file.attribute !== attribute)
                     return true;
-                this.heldBytes -= file.bytes.byteLength;
+                this.heldBytes -= heldBytesOf(file.bytes);
                 return false;
             });
             if (kept.length)
@@ -586,7 +599,7 @@ export class HueTransport {
         }
         const tally = newTally();
         for (const file of files) {
-            if (!file.bytes.byteLength)
+            if (!sizeOf(file.bytes))
                 continue;
             const refused = this.uploader?.refusal();
             if (!this.holdsValues() || refused) {
@@ -597,14 +610,14 @@ 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 + file.bytes.byteLength > MAX_HELD_BLOB_BYTES) {
+                this.heldBytes + heldBytesOf(file.bytes) > 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.heldBytes += heldBytesOf(file.bytes);
             this.ownMedia(span, identity);
         }
         if (tally.fallbacks.size)
@@ -621,7 +634,7 @@ export class HueTransport {
         const tally = newTally();
         const staged = [];
         for (const file of files) {
-            if (!file.bytes.byteLength)
+            if (!sizeOf(file.bytes))
                 continue;
             const refused = this.uploader?.refusal();
             if (!this.holdsValues() || refused)
@@ -648,7 +661,7 @@ export class HueTransport {
         if (!pending)
             return;
         this.logParts.delete(body);
-        const size = pending.files.reduce((total, file) => total + file.bytes.byteLength, 0);
+        const size = pending.files.reduce((total, file) => total + heldBytesOf(file.bytes), 0);
         if (this.heldBytes + size > MAX_HELD_BLOB_BYTES) {
             const tally = newTally();
             for (const _file of pending.files)
@@ -711,7 +724,7 @@ export class HueTransport {
         if (!files)
             return;
         for (const file of files)
-            this.heldBytes -= file.bytes.byteLength;
+            this.heldBytes -= heldBytesOf(file.bytes);
         this.media.delete(identity);
     }
     sweepMedia() {
@@ -822,13 +835,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) {

package/dist/types.d.ts

@@ -256,11 +256,19 @@ export interface FileRecord {
     mediaType: string;
     /** Hex SHA-256 of the file's bytes; computed from `data` when omitted. */
     sha256?: string;
-    /** Upload supplied bytes on this span when content capture is enabled. Defaults to false. */
+    /** Upload the file's bytes (`data`, or the file at `path`) on this span when content capture is
+     * enabled. Defaults to false. */
     upload?: boolean;
     /** The file's bytes, hashed and measured locally by default; a string is hashed as UTF-8.
-     * Data larger than 25 MiB is omitted and counted as an instrumentation failure. */
+     * Data larger than 25 MiB, which would be held in memory until it is uploaded, is omitted and
+     * counted as an instrumentation failure. Give `data` or `path`, not both. */
     data?: Uint8Array | string;
+    /** A file to hash and measure locally (Node.js file system) instead of `data`. Up to 25 MiB it is
+     * read now, as `data` is. A larger regular file, up to Hue's 1 GB upload limit, is hashed now a
+     * slice at a time and, with `upload: true`, read again from disk when it is uploaded: it must
+     * stay unchanged until the client flushes, and is uploaded only if it still has the size and
+     * SHA-256 it was recorded with (otherwise it counts as an upload fallback). */
+    path?: string;
     /** Size in bytes; computed from `data` when omitted. */
     byteSize?: number;
     /** File name, recorded as `hue.file.name` only when `captureContent` is true. */

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

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

package/package.json

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