@hue-run/sdk 0.16.0 → 0.18.0

package/dist/snapshot.js

@@ -1,7 +1,7 @@
 import { createTraceState } from "@opentelemetry/api";
 import { types as utilTypes } from "node:util";
 import { resourceFromAttributes } from "@opentelemetry/resources";
-import { hashInlineFiles, INLINE_FILE_LIMIT, INLINE_FILE_TEXT_PER_RECORD, isMessageKey, } from "./inline-files.js";
+import { hashInlineFiles, hashNestedInlineFiles, INLINE_FILE_TEXT_PER_RECORD, MAX_INLINE_FILE_TEXT, isMediaKey, isMessageKey, literalKeys, mayInlineFiles, readingOf, } from "./inline-files.js";
 import { scrubsToolCredentials, scrubToolCredentials } from "./tool-definitions.js";
 import { MAX_RECORD_NODES } from "./config.js";
 import { truncatedMarker } from "./privacy.js";
@@ -20,6 +20,25 @@ function cutToUnits(value, units) {
     // A slice can keep the whole original string alive; the copy holds only what is kept.
     return Buffer.from(value.slice(0, end), "utf16le").toString("utf16le");
 }
+/** Whether a long string may be a file's inline content: a `data:` URL or base64 text. */
+function mayBeFileContent(text) {
+    return text.startsWith("data:") || (text.length % 4 === 0 && /^[A-Za-z0-9+/]*={0,2}$/.test(text));
+}
+/** Whether a log record is a correlated GenAI event with a structured body, whose media may be
+ * uploaded under its trace. */
+function offloadsLogBody(source) {
+    const name = source.eventName ?? source.attributes?.["event.name"];
+    const body = source.body;
+    const traceId = source.spanContext?.traceId;
+    return (typeof name === "string" &&
+        name.startsWith("gen_ai.") &&
+        body !== null &&
+        typeof body === "object" &&
+        !utilTypes.isUint8Array(body) &&
+        typeof traceId === "string" &&
+        /^[0-9a-f]{32}$/.test(traceId) &&
+        !/^0+$/.test(traceId));
+}
 /** The record's byte or value budget ran out: a span's events and links past it are left out and
  * counted as dropped, where anything else loses the record. */
 class BudgetExceeded extends RangeError {
@@ -30,6 +49,8 @@ class Snapshot {
     captureContent;
     valueUnits;
     hold;
+    memo;
+    traceId;
     bytes = 512;
     unresolvedResource = false;
     /** The value strings this snapshot cut to `valueUnits`; export recognizes them, so the
@@ -38,28 +59,48 @@ class Snapshot {
     nodes = 0;
     ancestors = new Set();
     copied = new Map();
+    attributesCopied = new Map();
+    ownAttributesCopied = new Map();
+    /** Message texts as the queue copies them, their media as their digest: a span's own, and
+     * nested or a log record's (small binary media kept). */
     hashed = new Map();
+    nestedHashed = new Map();
+    /** Inspected texts as they would be exported with every file as its digest, by how their
+     * attribute is read: what the queue is charged for a value held whole for upload. */
+    charged = new Map();
     inspected = 0;
     /** Bytes of values held whole for upload, charged to the held-value budget. */
     held = 0;
     /** Set while the span's own attributes are copied: only they may be held for upload. */
     own = false;
-    /** The span's own messages whose large inline files shrank to their digest when queued, by
+    /** The own attributes holding literal text, while they are copied. */
+    literal = new Set();
+    /** Set for a log record: only its inspected attributes' media and its body's are held. */
+    log = false;
+    /** Set while a GenAI log record's structured body is copied: a long string that may be a
+     * file's content is held whole for upload. */
+    holdingBody = false;
+    /** The span's own messages whose inline media shrank to their digest when queued, by
      * attribute: the text queued (cut or not), and how many files it lost. */
     digested = new Map();
     /** How many files each message text {@link inlineFiles} hashed replaced by their digest. */
     hashedFiles = new Map();
+    /** The span's own message attributes inspected within the record's allowance, whether here or
+     * left to export for a message held whole: export inspects only these. */
+    inspectedKeys = new Set();
     /**
      * In metadata-only mode the recorded messages, which export strips, are not copied at all. A
      * value string (an attribute's, an event's or link's attribute's, a log body or a status
      * message) longer than `valueUnits` is cut to that length: export cuts it to the value cap
      * anyway, and charging it whole could drop the record before that cut ever ran.
      */
-    constructor(limit, captureContent = true, valueUnits = Infinity, hold) {
+    constructor(limit, captureContent = true, valueUnits = Infinity, hold, memo, traceId = "") {
         this.limit = limit;
         this.captureContent = captureContent;
         this.valueUnits = valueUnits;
         this.hold = hold;
+        this.memo = memo;
+        this.traceId = traceId;
     }
     /** Whether the held-value budget takes `bytes` more, charging them when it does. */
     holds(bytes) {
@@ -74,33 +115,51 @@ class Snapshot {
      * longer than the queued value length or bytes over the cap, within the held-value budget, and
      * a recorded message that may inline a large file kept as it is (export uploads the file).
      * Undefined for a value copied as before; text over the length the budget cannot hold is then
-     * cut and its large inline files shrink to their digest, as before uploads existed.
+     * cut and its inline media shrink to their digest, as before uploads existed.
      */
     heldValue(key, value) {
         if (!this.hold || !this.own)
             return undefined;
         if (typeof value === "string") {
+            // Literal text (`input.value` declared `text/plain`) is no JSON Hue reads files from: it is
+            // never inspected for media, but a span's value over the cap is still held whole to upload.
+            const literal = this.literal.has(key);
+            // A log record's value is never uploaded whole: only the media in its inspected attributes.
+            if (this.log && (literal || !isMediaKey(key)))
+                return undefined;
             if (value.length > this.valueUnits) {
+                if (this.log && (value.length > MAX_INLINE_FILE_TEXT || !mayInlineFiles(key, value)))
+                    return undefined;
                 // The queue must take the cut the value falls back to, as it would have taken it before.
                 const fallback = this.valueUnits * 2 + 16;
                 if (this.bytes + fallback > this.limit || !this.holds(value.length * 2))
                     return undefined;
                 this.charge(fallback);
+                // Export parses the held message; its inspection allowance is taken here, in order. A
+                // log record's export inspects within its own allowance.
+                if (!this.log &&
+                    !literal &&
+                    value.length <= MAX_INLINE_FILE_TEXT &&
+                    mayInlineFiles(key, value) &&
+                    this.inspected + value.length <= INLINE_FILE_TEXT_PER_RECORD) {
+                    this.inspected += value.length;
+                    this.inspectedKeys.add(key);
+                }
                 return { value };
             }
-            // Within the queued length: a recorded message holding a large inline file is held whole
-            // for export to upload the file, within the held-value budget, and the queue is charged
-            // its copy with the files as their digest, as before. Past the budget, the files shrink to
-            // their digest when queued, as before uploads existed.
-            if (!isMessageKey(key))
+            // Within the queued length: an inspected attribute holding inline media is held whole for
+            // export to upload the files, within the held-value budget, and the queue is charged its
+            // copy with the files as their digest. Past the budget, a recorded message's files shrink to
+            // their digest when queued, as before uploads existed; any other value is queued as it is.
+            if (!isMediaKey(key) || literal)
                 return undefined;
-            const digested = this.inlineFiles(key, value);
+            const digested = this.inlineFiles(key, value, true);
             if (digested === value || !this.holds(value.length * 2))
                 return undefined;
             this.copy(digested, 1, "value", true);
             return { value };
         }
-        if (!utilTypes.isUint8Array(value))
+        if (this.log || !utilTypes.isUint8Array(value))
             return undefined;
         const length = typedArrayByteLength.call(value);
         // Bytes over Hue's upload limit could only be exported cut: not copied whole for that.
@@ -119,7 +178,12 @@ class Snapshot {
             throw new BudgetExceeded("Telemetry byte budget exceeded");
     }
     mark() {
-        return { bytes: this.bytes, nodes: this.nodes, copied: this.copied.size };
+        return {
+            bytes: this.bytes,
+            nodes: this.nodes,
+            copied: this.copied.size,
+            attributesCopied: this.attributesCopied.size,
+        };
     }
     /** Back to `mark`, forgetting the values copied since: a later copy must not reuse a partial
      * copy of an item that was left out. */
@@ -131,6 +195,10 @@ class Snapshot {
         for (const key of [...this.copied.keys()])
             if (index++ >= mark.copied)
                 this.copied.delete(key);
+        index = 0;
+        for (const key of [...this.attributesCopied.keys()])
+            if (index++ >= mark.attributesCopied)
+                this.attributesCopied.delete(key);
     }
     /**
      * As many of a span's newest `items` (its events or links) as the record's budget still holds,
@@ -163,7 +231,7 @@ class Snapshot {
         return { kept, dropped: count - kept.length };
     }
     /**
-     * An attribute map. A large inline file in a message attribute shrinks to its digest before it
+     * An attribute map. A inline media part in a message attribute shrinks to its digest before it
      * is charged: export replaces it anyway, and charging the file could drop the whole record.
      */
     attributes(value) {
@@ -172,29 +240,58 @@ class Snapshot {
     /** The span's own attribute map, whose values over the cap may be held whole for upload. */
     ownAttributes(value) {
         this.own = true;
+        this.literal = literalKeys(value);
         try {
             return this.attributes(value);
         }
         finally {
             this.own = false;
+            this.literal = new Set();
         }
     }
-    /** A message attribute with its large inline files hashed. The same text is hashed once per
-     * record, and a record inspects at most {@link INLINE_FILE_TEXT_PER_RECORD} of it in all;
-     * beyond that, messages are charged as recorded. */
-    inlineFiles(key, value) {
-        // A UTF-16 unit is at most three UTF-8 bytes, so shorter text cannot hold a file to hash.
-        if (typeof value !== "string" || !isMessageKey(key) || value.length * 3 <= INLINE_FILE_LIMIT)
+    /**
+     * An attribute with its inline media hashed. As queued (`charge` false), only a recorded message
+     * shrinks: a span's own with every binary file and text file over the inline limit as its
+     * digest, a nested one's or a log record's keeping small binary media. With `charge`, any
+     * inspected attribute as export would place it with every file as its digest, what the queue is
+     * charged for a value held whole for upload. Own, nested and charged copies cache separately. A
+     * record inspects at most {@link INLINE_FILE_TEXT_PER_RECORD} code units in all; beyond that,
+     * values are charged as recorded. Nothing is inspected in metadata-only mode.
+     */
+    inlineFiles(key, value, charge = false) {
+        if (!this.captureContent ||
+            typeof value !== "string" ||
+            value.length > MAX_INLINE_FILE_TEXT ||
+            !mayInlineFiles(key, value) ||
+            (!charge && !isMessageKey(key)))
             return value;
-        if (this.hashed.has(value))
-            return this.hashed.get(value);
+        const own = this.own && !this.log;
+        // A span's own message is queued as it is charged: one copy serves both.
+        const shared = own && isMessageKey(key);
+        let hashed;
+        if (charge && !shared) {
+            const reading = readingOf(key);
+            hashed = this.charged.get(reading) ?? new Map();
+            this.charged.set(reading, hashed);
+        }
+        else
+            hashed = own ? this.hashed : this.nestedHashed;
+        if (hashed.has(value)) {
+            if (own)
+                this.inspectedKeys.add(key);
+            return hashed.get(value);
+        }
         if (this.inspected + value.length > INLINE_FILE_TEXT_PER_RECORD)
             return value;
         this.inspected += value.length;
+        if (own)
+            this.inspectedKeys.add(key);
         const count = { files: 0 };
-        const result = hashInlineFiles(key, value, count);
-        this.hashed.set(value, result);
-        if (count.files)
+        const result = charge || own
+            ? hashInlineFiles(key, value, count, this.memo, this.traceId, true)
+            : hashNestedInlineFiles(key, value);
+        hashed.set(value, result);
+        if (shared && count.files)
             this.hashedFiles.set(value, count.files);
         return result;
     }
@@ -240,6 +337,19 @@ class Snapshot {
     value(value, depth = 1) {
         return this.copy(value, depth, "value", true);
     }
+    /** A GenAI log record's structured body: strings are cut to the queued value length as in
+     * {@link value}, except that a longer string that may be a file's content (a `data:` URL or
+     * base64) within the inspection limit is held whole for export to upload, within the
+     * held-value budget, the queue charged what its cut would have cost. */
+    heldBody(value) {
+        this.holdingBody = this.hold !== undefined;
+        try {
+            return this.copy(value, 1, "value", true);
+        }
+        finally {
+            this.holdingBody = false;
+        }
+    }
     copy(value, depth = 0, shape = "value", content = false) {
         if (++this.nodes > MAX_RECORD_NODES)
             throw new BudgetExceeded("Telemetry complexity limit exceeded");
@@ -249,6 +359,13 @@ class Snapshot {
         if (typeof value === "string") {
             let text = value;
             if (content && text.length > this.valueUnits) {
+                if (this.holdingBody && text.length <= MAX_INLINE_FILE_TEXT && mayBeFileContent(text)) {
+                    const fallback = this.valueUnits * 2 + 16;
+                    if (this.bytes + fallback <= this.limit && this.holds(text.length * 2)) {
+                        this.charge(fallback);
+                        return text;
+                    }
+                }
                 text = cutToUnits(text, this.valueUnits);
                 this.cut.add(text);
             }
@@ -266,8 +383,15 @@ class Snapshot {
             throw new TypeError("Telemetry proxies are unsupported");
         if (this.ancestors.has(value))
             throw new TypeError("Cyclic telemetry value");
-        if (this.copied.has(value))
-            return this.copied.get(value);
+        // One object can be reused as own attributes, nested attributes and an ordinary log body.
+        // Their copies differ: only attributes inspect media, and only own attributes upload it.
+        const copies = shape === "attributes"
+            ? this.own
+                ? this.ownAttributesCopied
+                : this.attributesCopied
+            : this.copied;
+        if (copies.has(value))
+            return copies.get(value);
         if (utilTypes.isUint8Array(value)) {
             // Own accessors/subclasses cannot disguise the retained byte count.
             // A length-tracking SharedArrayBuffer view can grow on another thread
@@ -277,14 +401,14 @@ class Snapshot {
             this.charge(length);
             const copy = new Uint8Array(length);
             typedArraySet.call(copy, value);
-            this.copied.set(value, copy);
+            copies.set(value, copy);
             return copy;
         }
         const array = Array.isArray(value);
         if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
             throw new TypeError("Telemetry must contain data objects");
         const copy = array ? [] : Object.create(null);
-        this.copied.set(value, copy);
+        copies.set(value, copy);
         this.ancestors.add(value);
         if (array) {
             if (value.length > MAX_RECORD_NODES)
@@ -316,9 +440,13 @@ class Snapshot {
                     ? this.scrubbedBeforeCut(key, this.inlineFiles(key, source))
                     : source, depth + 1, shape === "event" && key === "attributes" ? "attributes" : "value", content || shape === "attributes");
                 copy[key] = copied;
-                // A span's own message whose large inline files shrank to their digest is named as it
+                // A span's own message whose inline media shrank to their digest is named as it
                 // was queued, cut or not, so export reports each file as not uploaded.
-                const files = this.own && shape === "attributes" && typeof source === "string"
+                const files = this.own &&
+                    !this.log &&
+                    shape === "attributes" &&
+                    typeof source === "string" &&
+                    isMessageKey(key)
                     ? this.hashedFiles.get(source)
                     : undefined;
                 if (files && typeof copied === "string")
@@ -360,7 +488,7 @@ class Snapshot {
             if (value == null || Object.hasOwn(attributes, key))
                 continue;
             this.charge(key.length * 2 + 16);
-            attributes[key] = this.copy(this.scrubbedBeforeCut(key, value), 0, "value", true);
+            attributes[key] = this.copy(this.scrubbedBeforeCut(key, this.inlineFiles(key, value)), 0, "value", true);
         }
         return resourceFromAttributes(attributes, { schemaUrl: this.copy(source.schemaUrl) });
     }
@@ -368,8 +496,8 @@ class Snapshot {
 function contextReader(context) {
     return () => context;
 }
-export function snapshotSpan(source, limit, captureContent = true, valueUnits = Infinity, hold) {
-    const snapshot = new Snapshot(limit, captureContent, valueUnits, hold);
+export function snapshotSpan(source, limit, captureContent = true, valueUnits = Infinity, hold, memo) {
+    const snapshot = new Snapshot(limit, captureContent, valueUnits, hold, memo, source.spanContext().traceId);
     const context = snapshot.context(source.spanContext());
     const fields = snapshot.copy({
         name: source.name,
@@ -416,10 +544,16 @@ export function snapshotSpan(source, limit, captureContent = true, valueUnits =
         cut: snapshot.cut,
         held: snapshot.held,
         digested: snapshot.digested,
+        inspected: snapshot.inspectedKeys,
     };
 }
-export function snapshotLog(source, limit, captureContent = true, valueUnits = Infinity) {
-    const snapshot = new Snapshot(limit, captureContent, valueUnits);
+export function snapshotLog(source, limit, captureContent = true, valueUnits = Infinity, hold, memo) {
+    // A log record's media upload under its own trace: an uncorrelated record holds none.
+    const traceId = source.spanContext?.traceId;
+    const correlated = typeof traceId === "string" && /^[0-9a-f]{32}$/.test(traceId) && !/^0+$/.test(traceId);
+    const holding = correlated ? hold : undefined;
+    const snapshot = new Snapshot(limit, captureContent, valueUnits, holding, memo, traceId ?? "");
+    snapshot.log = true;
     // Only our batching processor sees this copy. Its writer methods deliberately
     // cannot mutate the admitted snapshot or invalidate its charged byte count.
     const record = {
@@ -432,8 +566,12 @@ export function snapshotLog(source, limit, captureContent = true, valueUnits = I
             instrumentationScope: source.instrumentationScope,
             droppedAttributesCount: source.droppedAttributesCount,
         }),
-        body: snapshot.value(source.body),
-        attributes: snapshot.attributes(source.attributes),
+        body: holding && captureContent && offloadsLogBody(source)
+            ? snapshot.heldBody(source.body)
+            : snapshot.value(source.body),
+        attributes: holding
+            ? snapshot.ownAttributes(source.attributes)
+            : snapshot.attributes(source.attributes),
         spanContext: snapshot.context(source.spanContext),
         resource: snapshot.resource(source.resource),
         setAttribute() {
@@ -460,7 +598,8 @@ export function snapshotLog(source, limit, captureContent = true, valueUnits = I
         bytes: snapshot.bytes,
         unresolvedResource: snapshot.unresolvedResource,
         cut: snapshot.cut,
-        held: 0,
+        held: snapshot.held,
         digested: new Map(),
+        inspected: new Set(),
     };
 }

package/dist/transport.d.ts

@@ -79,11 +79,19 @@ export declare class HueTransport {
     private holdsReleased;
     private admissionCuts;
     private admissionDigests;
+    private admissionInspected;
     /** Uploads values over the inline limit apart from their spans; absent when disabled. */
     private uploader?;
     /** Bytes of values over the inline limit queued spans hold whole for upload, and each span's. */
     private heldBytes;
     private held;
+    private mediaMemo;
+    private media;
+    private logParts;
+    private logMedia;
+    private mediaOwners;
+    private mediaTimer?;
+    private mediaFinalizer;
     private uploaded;
     private uploadFallbacks;
     constructor(options: HueOptions);
@@ -98,6 +106,16 @@ export declare class HueTransport {
     private announceLiveSpans;
     private stopLiveTimer;
     private stopLiveSpans;
+    /** 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. */
+    private admitLogParts;
+    /** Registers a span whose staged files are released if it is never exported. */
+    private ownMedia;
+    private mediaIdentity;
+    private releaseMedia;
+    private protectMedia;
+    private releaseMediaIdentity;
+    private sweepMedia;
     /** Bounded: a trace whose root never arrives (an abandoned run) gives way to newer ones. */
     private countDropped;
     /** Cumulative counters and current queue gauges. */