@hue-run/sdk 0.13.2 → 0.15.0

package/dist/snapshot.js

@@ -2,32 +2,165 @@ 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 { scrubsToolCredentials, scrubToolCredentials } from "./tool-definitions.js";
+import { MAX_RECORD_NODES } from "./config.js";
+import { truncatedMarker } from "./privacy.js";
+import { MAX_BLOB_BYTES } from "./blobs.js";
 // Intrinsic accessors are captured once and invoked with an explicit receiver so a
 // hostile object cannot override them; the unbound reference is the point.
 // eslint-disable-next-line @typescript-eslint/unbound-method
 const typedArrayByteLength = Object.getOwnPropertyDescriptor(Object.getPrototypeOf(Uint8Array.prototype), "byteLength").get;
 // eslint-disable-next-line @typescript-eslint/unbound-method
 const typedArraySet = Uint8Array.prototype.set;
+/** `value` cut to at most `units` UTF-16 code units, never between the halves of a pair. */
+function cutToUnits(value, units) {
+    if (value.length <= units)
+        return value;
+    const end = /[\uD800-\uDBFF]/.test(value[units - 1] ?? "") ? units - 1 : 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");
+}
+/** 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 {
+}
 /** Copies only exported data, with the same finite budget used for admission. */
 class Snapshot {
     limit;
     captureContent;
+    valueUnits;
+    hold;
     bytes = 512;
     unresolvedResource = false;
+    /** The value strings this snapshot cut to `valueUnits`; export recognizes them, so the
+     * redactor's answer for one loses the end the redactor saw without its continuation. */
+    cut = new Set();
     nodes = 0;
     ancestors = new Set();
     copied = new Map();
     hashed = new Map();
     inspected = 0;
-    /** In metadata-only mode the recorded messages, which export strips, are not copied at all. */
-    constructor(limit, captureContent = true) {
+    /** 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
+     * 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();
+    /**
+     * 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) {
         this.limit = limit;
         this.captureContent = captureContent;
+        this.valueUnits = valueUnits;
+        this.hold = hold;
+    }
+    /** Whether the held-value budget takes `bytes` more, charging them when it does. */
+    holds(bytes) {
+        const hold = this.hold;
+        if (this.held + bytes > hold.budget && !(hold.first && this.held === 0))
+            return false;
+        this.held += bytes;
+        return true;
+    }
+    /**
+     * One of the span's own attribute values held whole for export to upload, when it may be: text
+     * 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.
+     */
+    heldValue(key, value) {
+        if (!this.hold || !this.own)
+            return undefined;
+        if (typeof value === "string") {
+            if (value.length > this.valueUnits) {
+                // 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);
+                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))
+                return undefined;
+            const digested = this.inlineFiles(key, value);
+            if (digested === value || !this.holds(value.length * 2))
+                return undefined;
+            this.copy(digested, 1, "value", true);
+            return { value };
+        }
+        if (!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.
+        if (length <= this.hold.valueBytes || length > MAX_BLOB_BYTES || !this.holds(length))
+            return undefined;
+        this.charge(16);
+        // Copied, so a later change by the application cannot alter what was recorded; charged to
+        // the held-value budget instead of the queue's.
+        const copy = new Uint8Array(length);
+        typedArraySet.call(copy, value);
+        return { value: copy };
     }
     charge(bytes) {
         this.bytes += bytes;
         if (this.bytes > this.limit)
-            throw new RangeError("Telemetry byte budget exceeded");
+            throw new BudgetExceeded("Telemetry byte budget exceeded");
+    }
+    mark() {
+        return { bytes: this.bytes, nodes: this.nodes, copied: this.copied.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. */
+    restore(mark) {
+        this.bytes = mark.bytes;
+        this.nodes = mark.nodes;
+        this.ancestors.clear();
+        let index = 0;
+        for (const key of [...this.copied.keys()])
+            if (index++ >= mark.copied)
+                this.copied.delete(key);
+    }
+    /**
+     * As many of a span's newest `items` (its events or links) as the record's budget still holds,
+     * each copied by `copyItem`, and how many older ones it could not hold, as OpenTelemetry keeps a
+     * span's newest events and links past its own count limits. A span whose events or links
+     * outgrow the budget keeps its name, timing, attributes and the rest of them, counting the ones
+     * left out as dropped, instead of being lost whole.
+     */
+    newest(items, copyItem) {
+        if (!Array.isArray(items) || utilTypes.isProxy(items))
+            throw new TypeError("Telemetry must contain data objects");
+        const count = items.length;
+        const kept = [];
+        for (let index = count - 1; index >= 0; index--) {
+            const descriptor = Object.getOwnPropertyDescriptor(items, index);
+            if (descriptor && !("value" in descriptor))
+                throw new TypeError("Telemetry accessors are unsupported");
+            const mark = this.mark();
+            try {
+                kept.push(copyItem(descriptor?.value));
+            }
+            catch (error) {
+                if (!(error instanceof BudgetExceeded))
+                    throw error;
+                this.restore(mark);
+                break;
+            }
+        }
+        kept.reverse();
+        return { kept, dropped: count - kept.length };
     }
     /**
      * An attribute map. A large inline file in a message attribute shrinks to its digest before it
@@ -36,6 +169,16 @@ class Snapshot {
     attributes(value) {
         return this.copy(value, 1, "attributes");
     }
+    /** The span's own attribute map, whose values over the cap may be held whole for upload. */
+    ownAttributes(value) {
+        this.own = true;
+        try {
+            return this.attributes(value);
+        }
+        finally {
+            this.own = false;
+        }
+    }
     /** 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. */
@@ -48,21 +191,69 @@ class Snapshot {
         if (this.inspected + value.length > INLINE_FILE_TEXT_PER_RECORD)
             return value;
         this.inspected += value.length;
-        const result = hashInlineFiles(key, value);
+        const count = { files: 0 };
+        const result = hashInlineFiles(key, value, count);
         this.hashed.set(value, result);
+        if (count.files)
+            this.hashedFiles.set(value, count.files);
         return result;
     }
-    /** Span events, whose attributes are attribute maps. */
-    events(value) {
-        return this.copy(value, 1, "events");
+    /**
+     * An attribute whose value will be cut and whose credentials export removes (tool definitions
+     * and recorded requests) has them removed first, from the whole value: a cut prefix no longer
+     * parses, so export could not find them in it. A value longer than what the record's budget has
+     * left is not parsed on the application's thread at all: the receiver's marker replaces it, as
+     * in the Python SDK, rather than a cut that could hold credentials.
+     */
+    scrubbedBeforeCut(key, value) {
+        if (this.valueUnits === Infinity || !scrubsToolCredentials(key))
+            return value;
+        const scrubbed = (units, scrub, bytes) => units * 2 > this.limit - this.bytes ? truncatedMarker(bytes()) : scrub();
+        if (typeof value === "string")
+            return value.length > this.valueUnits
+                ? scrubbed(value.length, () => scrubToolCredentials(key, value), () => Buffer.byteLength(value))
+                : value;
+        // A list of definitions (AI SDK 6 `ai.prompt.tools`), read through its own data properties;
+        // anything else is left for the copy to accept or refuse.
+        if (!Array.isArray(value) || utilTypes.isProxy(value) || value.length > MAX_RECORD_NODES)
+            return value;
+        const items = [];
+        let long = false;
+        let units = 0;
+        for (let index = 0; index < value.length; index++) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, index);
+            if (descriptor && !("value" in descriptor))
+                return value;
+            const item = descriptor?.value;
+            if (typeof item === "string") {
+                units += item.length;
+                if (item.length > this.valueUnits)
+                    long = true;
+            }
+            items.push(item);
+        }
+        return long
+            ? scrubbed(units, () => scrubToolCredentials(key, items), () => items.reduce((total, item) => total + (typeof item === "string" ? Buffer.byteLength(item) : 0), 0))
+            : value;
+    }
+    /** A value whose strings are cut to the queued value length: a log body or a status. */
+    value(value, depth = 1) {
+        return this.copy(value, depth, "value", true);
     }
-    copy(value, depth = 0, shape = "value") {
-        if (++this.nodes > 16384 || depth > 32)
-            throw new RangeError("Telemetry complexity limit exceeded");
+    copy(value, depth = 0, shape = "value", content = false) {
+        if (++this.nodes > MAX_RECORD_NODES)
+            throw new BudgetExceeded("Telemetry complexity limit exceeded");
+        if (depth > 32)
+            throw new RangeError("Telemetry nesting limit exceeded");
         this.charge(16);
         if (typeof value === "string") {
-            this.charge(value.length * 2);
-            return value;
+            let text = value;
+            if (content && text.length > this.valueUnits) {
+                text = cutToUnits(text, this.valueUnits);
+                this.cut.add(text);
+            }
+            this.charge(text.length * 2);
+            return text;
         }
         if (value === null ||
             value === undefined ||
@@ -96,13 +287,13 @@ class Snapshot {
         this.copied.set(value, copy);
         this.ancestors.add(value);
         if (array) {
-            if (value.length > 16384)
-                throw new RangeError("Telemetry complexity limit exceeded");
+            if (value.length > MAX_RECORD_NODES)
+                throw new BudgetExceeded("Telemetry complexity limit exceeded");
             for (let index = 0; index < value.length; index++) {
                 const descriptor = Object.getOwnPropertyDescriptor(value, index);
                 if (descriptor && !("value" in descriptor))
                     throw new TypeError("Telemetry accessors are unsupported");
-                copy.push(this.copy(descriptor?.value, depth + 1, shape === "events" ? "event" : "value"));
+                copy.push(this.copy(descriptor?.value, depth + 1, "value", content || shape === "attributes"));
             }
         }
         else {
@@ -115,7 +306,23 @@ class Snapshot {
                 if (shape === "attributes" && !this.captureContent && isMessageKey(key))
                     continue;
                 this.charge(key.length * 2 + 16);
-                copy[key] = this.copy(shape === "attributes" ? this.inlineFiles(key, descriptor.value) : descriptor.value, depth + 1, shape === "event" && key === "attributes" ? "attributes" : "value");
+                const held = shape === "attributes" ? this.heldValue(key, descriptor.value) : undefined;
+                if (held) {
+                    copy[key] = held.value;
+                    continue;
+                }
+                const source = descriptor.value;
+                const copied = this.copy(shape === "attributes"
+                    ? 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
+                // was queued, cut or not, so export reports each file as not uploaded.
+                const files = this.own && shape === "attributes" && typeof source === "string"
+                    ? this.hashedFiles.get(source)
+                    : undefined;
+                if (files && typeof copied === "string")
+                    this.digested.set(key, { text: copied, files });
             }
         }
         this.ancestors.delete(value);
@@ -153,7 +360,7 @@ class Snapshot {
             if (value == null || Object.hasOwn(attributes, key))
                 continue;
             this.charge(key.length * 2 + 16);
-            attributes[key] = this.copy(value);
+            attributes[key] = this.copy(this.scrubbedBeforeCut(key, value), 0, "value", true);
         }
         return resourceFromAttributes(attributes, { schemaUrl: this.copy(source.schemaUrl) });
     }
@@ -161,41 +368,58 @@ class Snapshot {
 function contextReader(context) {
     return () => context;
 }
-export function snapshotSpan(source, limit, captureContent = true) {
-    const snapshot = new Snapshot(limit, captureContent);
+export function snapshotSpan(source, limit, captureContent = true, valueUnits = Infinity, hold) {
+    const snapshot = new Snapshot(limit, captureContent, valueUnits, hold);
     const context = snapshot.context(source.spanContext());
-    if (source.links.length > 16384)
-        throw new RangeError("Link complexity limit exceeded");
-    const links = source.links.map((link) => ({
-        context: snapshot.context(link.context),
-        attributes: snapshot.attributes(link.attributes),
-        droppedAttributesCount: snapshot.copy(link.droppedAttributesCount),
-    }));
+    const fields = snapshot.copy({
+        name: source.name,
+        kind: source.kind,
+        startTime: source.startTime,
+        endTime: source.endTime,
+        duration: source.duration,
+        ended: source.ended,
+        instrumentationScope: source.instrumentationScope,
+        droppedAttributesCount: source.droppedAttributesCount,
+        droppedEventsCount: source.droppedEventsCount,
+        droppedLinksCount: source.droppedLinksCount,
+    });
+    const status = snapshot.value(source.status);
+    const attributes = snapshot.ownAttributes(source.attributes);
+    const parentSpanContext = snapshot.context(source.parentSpanContext);
+    const resource = snapshot.resource(source.resource);
+    // Last, with what the budget has left: past it, events and links are counted as dropped.
+    const events = snapshot.newest(source.events, (event) => snapshot.copy(event, 2, "event"));
+    const links = snapshot.newest(source.links, (item) => {
+        const link = item;
+        return {
+            context: snapshot.context(link.context),
+            attributes: snapshot.attributes(link.attributes),
+            droppedAttributesCount: snapshot.copy(link.droppedAttributesCount),
+        };
+    });
     const record = {
-        ...snapshot.copy({
-            name: source.name,
-            kind: source.kind,
-            startTime: source.startTime,
-            endTime: source.endTime,
-            duration: source.duration,
-            ended: source.ended,
-            status: source.status,
-            instrumentationScope: source.instrumentationScope,
-            droppedAttributesCount: source.droppedAttributesCount,
-            droppedEventsCount: source.droppedEventsCount,
-            droppedLinksCount: source.droppedLinksCount,
-        }),
-        attributes: snapshot.attributes(source.attributes),
-        events: snapshot.events(source.events),
+        ...fields,
+        droppedEventsCount: (fields.droppedEventsCount ?? 0) + events.dropped,
+        droppedLinksCount: (fields.droppedLinksCount ?? 0) + links.dropped,
+        status,
+        attributes,
+        events: events.kept,
         spanContext: contextReader(context),
-        parentSpanContext: snapshot.context(source.parentSpanContext),
-        links,
-        resource: snapshot.resource(source.resource),
+        parentSpanContext,
+        links: links.kept,
+        resource,
+    };
+    return {
+        record,
+        bytes: snapshot.bytes,
+        unresolvedResource: snapshot.unresolvedResource,
+        cut: snapshot.cut,
+        held: snapshot.held,
+        digested: snapshot.digested,
     };
-    return { record, bytes: snapshot.bytes, unresolvedResource: snapshot.unresolvedResource };
 }
-export function snapshotLog(source, limit, captureContent = true) {
-    const snapshot = new Snapshot(limit, captureContent);
+export function snapshotLog(source, limit, captureContent = true, valueUnits = Infinity) {
+    const snapshot = new Snapshot(limit, captureContent, valueUnits);
     // Only our batching processor sees this copy. Its writer methods deliberately
     // cannot mutate the admitted snapshot or invalidate its charged byte count.
     const record = {
@@ -205,10 +429,10 @@ export function snapshotLog(source, limit, captureContent = true) {
             severityText: source.severityText,
             severityNumber: source.severityNumber,
             eventName: source.eventName,
-            body: source.body,
             instrumentationScope: source.instrumentationScope,
             droppedAttributesCount: source.droppedAttributesCount,
         }),
+        body: snapshot.value(source.body),
         attributes: snapshot.attributes(source.attributes),
         spanContext: snapshot.context(source.spanContext),
         resource: snapshot.resource(source.resource),
@@ -231,5 +455,12 @@ export function snapshotLog(source, limit, captureContent = true) {
             return this;
         },
     };
-    return { record, bytes: snapshot.bytes, unresolvedResource: snapshot.unresolvedResource };
+    return {
+        record,
+        bytes: snapshot.bytes,
+        unresolvedResource: snapshot.unresolvedResource,
+        cut: snapshot.cut,
+        held: 0,
+        digested: new Map(),
+    };
 }

package/dist/tool-definitions.d.ts

@@ -21,6 +21,10 @@ export declare function scrubCredentialText(text: string, cut?: boolean): string
 /** `scrubCredentialText` without its bound on the text's length, for tests that time long texts;
  * callers use `scrubCredentialText`. */
 export declare function scrubCredentialTextUnbounded(text: string, cut?: boolean): string;
+/** Whether {@link scrubToolCredentials} inspects an attribute's value: its credentials must be
+ * removed from the whole recorded value, before anything cuts it to a prefix that no longer
+ * parses. */
+export declare function scrubsToolCredentials(key: string): boolean;
 /**
  * Removes hosted-tool credentials from an exported attribute value, before the caller's `redact`.
  * Tool definitions come from OpenTelemetry GenAI (`gen_ai.tool.definitions`), AI SDK 6

package/dist/tool-definitions.js

@@ -949,6 +949,17 @@ function scrubRequestText(text) {
             request[field] = scrubNode(request[field], state, 0, false);
     return state.changed ? JSON.stringify(request) : text;
 }
+/** Whether {@link scrubToolCredentials} inspects an attribute's value: its credentials must be
+ * removed from the whole recorded value, before anything cuts it to a prefix that no longer
+ * parses. */
+export function scrubsToolCredentials(key) {
+    return (key === "gen_ai.tool.definitions" ||
+        key === "ai.prompt.tools" ||
+        openInferenceTool.test(key) ||
+        key === "input.value" ||
+        key === "output.value" ||
+        key === "llm.invocation_parameters");
+}
 /**
  * Removes hosted-tool credentials from an exported attribute value, before the caller's `redact`.
  * Tool definitions come from OpenTelemetry GenAI (`gen_ai.tool.definitions`), AI SDK 6

package/dist/transport.d.ts

@@ -4,6 +4,17 @@ import { validateOptions } from "./config.js";
 import type { ExportIssue, ExportReport, HueOptions } from "./types.js";
 /** A finished span or emitted log record as the OpenTelemetry SDK hands it to a processor. */
 export type RecordValue = ReadableSpan | ReadableLogRecord;
+/**
+ * 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
+ * against the queue's bounds, and are sent again once `Retry-After` has passed. A longer wait loses
+ * them, reported like any refused request.
+ */
+export declare const MAX_RATE_LIMIT_HOLD_MILLIS = 60000;
+/** How long one export may take with requests of `timeoutMillis` each: its uploads of values over
+ * the inline limit, its requests, and a hold for a rate-limited receiver on top. Processors and
+ * providers wait this long for a drain. */
+export declare function exportBudgetMillis(timeoutMillis: number): number;
 /**
  * Rejection of {@link HueClient.flush} and {@link HueClient.shutdown}: telemetry was not fully
  * accepted. Carries sanitized counts only, never server response text or content.
@@ -62,6 +73,19 @@ export declare class HueTransport {
     private placeholders;
     private placeholderSources;
     private batchSpans?;
+    private limits;
+    /** The rate-limit holds in progress, each ended early by calling it. */
+    private holds;
+    private holdsReleased;
+    private admissionCuts;
+    private admissionDigests;
+    /** 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 uploaded;
+    private uploadFallbacks;
     constructor(options: HueOptions);
     /**
      * Advisory records (placeholders) are admitted only while the queue is under a quarter of its
@@ -74,6 +98,8 @@ export declare class HueTransport {
     private announceLiveSpans;
     private stopLiveTimer;
     private stopLiveSpans;
+    /** Bounded: a trace whose root never arrives (an abandoned run) gives way to newer ones. */
+    private countDropped;
     /** Cumulative counters and current queue gauges. */
     getReport(): ExportReport;
     /** Copies of the latest 128 sanitized issues, oldest first. */