@hue-run/sdk 0.12.1 → 0.13.1

package/dist/transport.js

@@ -9,7 +9,7 @@ import { isInsecureOrigin, MAX_BODY_BYTES, validateOptions } from "./config.js";
 import { announcesLiveSpan, LIVE_SPAN_INTERVAL_MILLIS, MAX_LIVE_SPANS, pendingPlaceholder, PLACEHOLDERS_HEADER, withoutPlaceholderMarkers, } from "./live-spans.js";
 import { estimateRecordBytes } from "./safety.js";
 import { snapshotLog, snapshotSpan } from "./snapshot.js";
-import { redactLog, redactSpan } from "./privacy.js";
+import { DROPPED_RECORDS_KEY, isContentKey, redactLog, redactSpan, TRUNCATED_KEY, truncatedMarker, withTruncatedKeys, } from "./privacy.js";
 import { sdkVersion } from "./version.js";
 /** Per-record allowance for protobuf length prefixes that grow when records are grouped. */
 const RECORD_FRAMING_BYTES = 64;
@@ -77,6 +77,10 @@ export class HueTransport {
     logs = new Map();
     pendingBytes = 0;
     dropped = { traces: 0, logs: 0 };
+    /** Records of each trace the SDK never sent (dropped from the queue, refused as invalid or
+     * 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();
     instrumentationFailures = 0;
     diagnosticPending = false;
     lastDiagnosticAt = -Infinity;
@@ -89,6 +93,8 @@ export class HueTransport {
     live = new Set();
     liveTimer;
     liveSpans;
+    // Whether this client announces live spans at all; `liveSpans` also goes off at shutdown.
+    announcesLiveSpans;
     placeholdersRejected = false;
     // Admitted placeholder snapshots and the marker attributes added after redaction.
     placeholders = new WeakMap();
@@ -99,6 +105,7 @@ export class HueTransport {
         this.options = validateOptions(options);
         Object.defineProperty(this, "options", { enumerable: false });
         this.liveSpans = this.options.enabled !== false && this.options.liveSpans;
+        this.announcesLiveSpans = this.liveSpans;
         this.traceExporter = new ReportingExporter(this, "traces", ProtobufTraceSerializer, TraceExporterMetricsHelper, (span, cache) => redactSpan(span, this.options, cache));
         this.logExporter = new ReportingExporter(this, "logs", ProtobufLogsSerializer, LogsExporterMetricsHelper, (log, cache) => redactLog(log, this.options, cache));
         if (this.options.enabled === false) {
@@ -280,13 +287,18 @@ export class HueTransport {
         return !this.placeholdersRejected;
     }
     /**
-     * @internal Exporter callback: a receiver without placeholder support rejects each by its zero
-     * end time. Stops announcing for this transport and records one warning.
+     * @internal Exporter callback: a trace acknowledgement lacked the placeholder-support header,
+     * so the receiver predates placeholders and rejects each by its zero end time; `count` is how
+     * many it rejected in that request, zero when the request carried none. Stops announcing for
+     * this transport and records one warning.
      */
     rejectPlaceholders(count) {
-        this.stopLiveSpans();
-        if (this.placeholdersRejected)
+        // A client that never announces live spans (by option or setup credential) records no
+        // warning about placeholders; one that does records it once, even when the acknowledgement
+        // arrives during its final flush, after shutdown has already stopped announcing.
+        if (!this.announcesLiveSpans || this.placeholdersRejected)
             return;
+        this.stopLiveSpans();
         this.placeholdersRejected = true;
         this.issue("traces", "warning", count, "This Hue server does not accept in-progress span placeholders; live spans are disabled");
     }
@@ -302,6 +314,25 @@ export class HueTransport {
     acceptedRecords(signal, count) {
         this.accepted[signal] += count;
     }
+    /** @internal Exporter callback: a trace's root span carries the count of its records the SDK
+     * never sent, read when the root is exported (a record lost after that is not counted: the
+     * root has left). The count stays until the request carrying the root is acknowledged
+     * (`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)
+            return span;
+        const count = this.droppedByTrace.get(span.spanContext().traceId);
+        if (!count)
+            return span;
+        return { ...span, attributes: { ...span.attributes, [DROPPED_RECORDS_KEY]: count } };
+    }
+    /** @internal Exporter callback: these traces' counts reached Hue on their roots, so the map
+     * holds nothing for a trace that has ended and told its losses. */
+    consumeDroppedRecords(traceIds) {
+        for (const traceId of traceIds)
+            this.droppedByTrace.delete(traceId);
+    }
     /** @internal Records a sanitized issue, updates counters and rate-limits the diagnostic callback. */
     issue(signal, kind, count, message, status, traceIds) {
         if (kind === "dropped")
@@ -310,6 +341,15 @@ export class HueTransport {
             this.rejected[signal] += count;
         else if (kind !== "warning")
             this.failed[signal] += count;
+        // A record lost before any request names its one trace; a failed batch is retried or
+        // reported as delivery, not counted here.
+        if ((kind === "dropped" || kind === "invalid") && count > 0 && traceIds?.length === 1) {
+            const [traceId] = traceIds;
+            // Bounded: a trace whose root never arrives (an abandoned run) gives way to newer ones.
+            if (this.droppedByTrace.size >= 1024 && !this.droppedByTrace.has(traceId))
+                this.droppedByTrace.delete(this.droppedByTrace.keys().next().value);
+            this.droppedByTrace.set(traceId, (this.droppedByTrace.get(traceId) ?? 0) + count);
+        }
         const issue = {
             sequence: ++this.sequence,
             signal,
@@ -480,6 +520,101 @@ function traceIdsOf(records) {
     // concern any trace in flight.
     return ids.size ? [...ids] : undefined;
 }
+/** The serialized size of one attribute value, for choosing what to shed first. */
+function valueBytes(value) {
+    if (typeof value === "string")
+        return Buffer.byteLength(value);
+    if (value instanceof Uint8Array)
+        return value.byteLength;
+    if (value !== null && typeof value === "object") {
+        try {
+            return Buffer.byteLength(JSON.stringify(value));
+        }
+        catch {
+            return 0;
+        }
+    }
+    return 8;
+}
+/** Whether a value is already the receiver's marker for a value that was shed. */
+function isTruncatedMarker(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        value[TRUNCATED_KEY] === true);
+}
+/**
+ * The record with its largest content value (a log's body before its attributes) replaced by
+ * the receiver's marker and listed under `hue.truncated`; undefined when no content value is
+ * left to shed. Metadata is never shed: a record too large without its content is lost whole.
+ */
+function shedLargestContent(record, signal) {
+    if (signal === "logs") {
+        const log = record;
+        if (log.body !== undefined && !isTruncatedMarker(log.body)) {
+            const bytes = valueBytes(log.body);
+            const attributes = {
+                ...log.attributes,
+                [TRUNCATED_KEY]: withTruncatedKeys(log.attributes[TRUNCATED_KEY], ["body"]),
+            };
+            return { ...log, body: truncatedMarker(bytes), attributes };
+        }
+    }
+    const { attributes } = record;
+    // The record's own content values, and a span's events' (listed as the receiver lists an
+    // event's cut: `event:<name>:<key>`).
+    const events = signal === "traces" ? record.events : [];
+    const links = signal === "traces" ? record.links : [];
+    let largest;
+    const consider = (where, index, key, value) => {
+        if (!isContentKey(key) || isTruncatedMarker(value))
+            return;
+        const bytes = valueBytes(value);
+        if (!largest || bytes > largest.bytes)
+            largest = { where, index, key, bytes };
+    };
+    for (const [key, value] of Object.entries(attributes))
+        consider("own", 0, key, value);
+    events.forEach((event, index) => {
+        for (const [key, value] of Object.entries(event.attributes ?? {}))
+            consider("event", index, key, value);
+    });
+    links.forEach((link, index) => {
+        for (const [key, value] of Object.entries(link.attributes ?? {}))
+            consider("link", index, key, value);
+    });
+    if (!largest)
+        return undefined;
+    const found = largest;
+    // Listed as the receiver lists a cut of the same place: the key alone, `event:<name>:<key>`,
+    // or `link:<key>`.
+    const listed = found.where === "own"
+        ? found.key
+        : found.where === "event"
+            ? `event:${events[found.index].name}:${found.key}`
+            : `link:${found.key}`;
+    const shed = {
+        ...attributes,
+        ...(found.where === "own" ? { [found.key]: truncatedMarker(found.bytes) } : {}),
+        [TRUNCATED_KEY]: withTruncatedKeys(attributes[TRUNCATED_KEY], [listed]),
+    };
+    const marker = { [found.key]: truncatedMarker(found.bytes) };
+    if (found.where === "own")
+        return { ...record, attributes: shed };
+    if (found.where === "event")
+        return {
+            ...record,
+            attributes: shed,
+            events: events.map((event, index) => index === found.index
+                ? { ...event, attributes: { ...event.attributes, ...marker } }
+                : event),
+        };
+    return {
+        ...record,
+        attributes: shed,
+        links: links.map((link, index) => index === found.index ? { ...link, attributes: { ...link.attributes, ...marker } } : link),
+    };
+}
 class ReportingExporter {
     transport;
     signal;
@@ -532,11 +667,17 @@ class ReportingExporter {
         return real;
     }
     async exportRecords(records) {
-        const accepted = [];
-        // Placeholders are advisory: losing one is a warning, never an export failure.
-        const placeholders = new Set();
+        // Completed records and placeholders travel in separate requests, completed records first,
+        // so a rejection count is always one kind of record's. Placeholders are advisory: losing one
+        // is a warning, never an export failure.
+        const real = [];
+        const pending = [];
         const cache = new WeakMap();
         let failed = false;
+        // A request of completed records the receiver refused or did not answer, as opposed to a
+        // record this side could not redact or encode: placeholders are advisory, so such a receiver
+        // gets no second request.
+        let refused = false;
         let redactedBytes = 0;
         const invalid = (placeholder, message, record) => {
             if (placeholder)
@@ -546,11 +687,6 @@ class ReportingExporter {
                 this.transport.issue(this.signal, "invalid", 1, message, undefined, record ? traceIdsOf([record]) : undefined);
             }
         };
-        const send = async (batch) => {
-            const count = batch.filter((record) => placeholders.has(record)).length;
-            if (!(await this.send(batch, count)))
-                failed = true;
-        };
         const resourceDeadline = Date.now() + this.transport.options.timeoutMillis;
         for (const { record, markers } of this.ordered(records)) {
             try {
@@ -587,9 +723,7 @@ class ReportingExporter {
                 if (redactedBytes + bytes > this.transport.options.maxQueueBytes)
                     throw new RangeError("Redacted batch exceeds byte budget");
                 redactedBytes += bytes;
-                accepted.push(redacted);
-                if (markers)
-                    placeholders.add(redacted);
+                (markers ? pending : real).push(redacted);
             }
             catch {
                 invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits", record);
@@ -600,43 +734,123 @@ class ReportingExporter {
         // encodings plus a fixed framing margin bounds the request size. Room is left for gzip
         // headers/blocks when otherwise incompressible data is near the wire cap.
         const limit = MAX_BODY_BYTES - 1024;
-        let batch = [];
-        let batchBytes = 0;
-        for (const record of accepted) {
-            let recordBytes;
-            try {
-                recordBytes = this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
+        const measure = (record) => this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
+        /** The record, shed until it fits the request limit, and its size; undefined when no content
+         * is left to shed. */
+        const fit = (record) => {
+            let bytes = measure(record);
+            // A record over the request limit sheds its content values, largest first, each
+            // replaced by the receiver's marker and listed under `hue.truncated`, until it fits:
+            // the span and what it still holds reach Hue, and a reader sees what was shed. Only a
+            // record too large without any content value is lost, and counted on its root.
+            while (bytes > limit) {
+                const shed = shedLargestContent(record, this.signal);
+                if (!shed)
+                    return undefined;
+                record = shed;
+                bytes = measure(record);
             }
-            catch {
-                invalid(placeholders.has(record), "Telemetry record could not be serialized", record);
-                continue;
-            }
-            const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
-            if (batch.length && batchBytes + framedBytes > limit) {
-                await send(batch);
+            return { record, bytes };
+        };
+        /** Sends one kind of record in requests up to the limit: completed records, whose roots carry
+         * their traces' dropped-record counts, or placeholders alone (`advisory`). */
+        const pack = async (accepted, advisory) => {
+            let batch = [];
+            let batchBytes = 0;
+            // The traces whose root in the batch carries its dropped-record count, consumed once the
+            // request that carries it is acknowledged; a failed request keeps the count.
+            let counted = [];
+            const send = async () => {
+                const records = batch;
+                const traces = counted;
                 batch = [];
                 batchBytes = 0;
+                counted = [];
+                // A request of placeholders never fails the export, and none follows an acknowledgement
+                // that turned live spans off.
+                if (advisory && !this.transport.sendsPlaceholders())
+                    return;
+                if (await this.send(records, advisory ? records.length : 0)) {
+                    this.transport.consumeDroppedRecords(traces);
+                }
+                else if (!advisory) {
+                    failed = true;
+                    refused = true;
+                }
+            };
+            // Every record is measured, shed and, where it cannot be sent, counted lost before any root
+            // is written, so a root carries the losses of children that ended after it.
+            const prepared = [];
+            for (const record of accepted) {
+                let fitted;
+                try {
+                    fitted = fit(record);
+                }
+                catch {
+                    invalid(advisory, "Telemetry record could not be serialized", record);
+                    continue;
+                }
+                if (!fitted) {
+                    invalid(advisory, "Telemetry record exceeds the 1 MiB request limit", record);
+                    continue;
+                }
+                prepared.push(fitted);
             }
-            if (recordBytes > limit) {
-                invalid(placeholders.has(record), "Telemetry record exceeds the 1 MiB request limit", record);
-                continue;
+            for (const entry of prepared) {
+                let { record, bytes: recordBytes } = entry;
+                let carriesCount = false;
+                if (this.signal === "traces" && !advisory) {
+                    const withCount = this.transport.withDroppedRecords(record);
+                    if (withCount !== record) {
+                        carriesCount = true;
+                        // The count may put a root shed to just under the limit over it again: shed on.
+                        let fitted;
+                        try {
+                            fitted = fit(withCount);
+                        }
+                        catch {
+                            invalid(false, "Telemetry record could not be serialized", withCount);
+                            continue;
+                        }
+                        if (!fitted) {
+                            invalid(false, "Telemetry record exceeds the 1 MiB request limit", withCount);
+                            continue;
+                        }
+                        ({ record, bytes: recordBytes } = fitted);
+                    }
+                }
+                const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
+                if (batch.length && batchBytes + framedBytes > limit)
+                    await send();
+                batch.push(record);
+                batchBytes += framedBytes;
+                if (carriesCount)
+                    counted.push(record.spanContext().traceId);
             }
-            batch.push(record);
-            batchBytes += framedBytes;
-        }
-        if (batch.length)
-            await send(batch);
+            if (batch.length)
+                await send();
+        };
+        await pack(real, false);
+        // None is sent once a receiver answered without placeholder support, which the completed
+        // records' acknowledgements may have just shown, nor after this export's completed records were
+        // refused or unanswered: a receiver that just refused or timed out gets no second request with
+        // its own retries. A record this side could not send keeps the placeholders going out.
+        if (pending.length && !refused && this.transport.sendsPlaceholders())
+            await pack(pending, true);
         if (failed)
             throw new Error("Hue telemetry export failed");
     }
-    /** Sends one request; `placeholders` of `records` are advisory and never count as lost. */
+    /**
+     * Sends one request: of completed records, or of placeholders alone when `placeholders` is
+     * `records.length`. Placeholders are advisory and never count as lost.
+     */
     async send(records, placeholders = 0) {
         const options = this.transport.options;
         const real = records.length - placeholders;
         // The traces this batch carries, spans or the log records emitted in their spans, so a loss
         // or rejection names whose telemetry it was.
         const traceIds = traceIdsOf(records);
-        // A loss involving only placeholders is a warning. Mixed losses count only real records.
+        // Losing a request of placeholders is a warning; losing one of completed records counts them.
         const lose = (message, status) => {
             this.transport.issue(this.signal, real ? "failed" : "warning", real || placeholders, real ? message : `${message} (in-progress span placeholders only)`, status, traceIds);
             return !real;
@@ -660,26 +874,32 @@ class ReportingExporter {
                     const count = Number(partial?.[this.signal === "traces" ? "rejectedSpans" : "rejectedLogRecords"] ?? 0);
                     if (!Number.isSafeInteger(count) || count < 0 || count > records.length)
                         throw new Error("Invalid rejection count");
-                    // A receiver that accepts placeholders never rejects them for being placeholders, so its
-                    // rejections count as before. One without the header predates them and rejects each.
-                    const downgrade = placeholders > 0 && !acceptsPlaceholders;
-                    const placeholderRejections = downgrade ? Math.min(count, placeholders) : 0;
-                    if (downgrade)
-                        this.transport.rejectPlaceholders(placeholderRejections);
-                    const remaining = count - placeholderRejections;
-                    // Rejections are not matched to records. Attribute them to real records first. A
-                    // rejection of spans in a batch of one trace is that trace's; in a batch of several it
-                    // names none, since the innocent traces' spans may have been accepted, and each case's
-                    // receipt decides. A rejection of log records names every trace in the batch: the
-                    // receipt counts spans, not logs, so it could not tell whose logs were lost.
-                    rejected = Math.min(remaining, real);
+                    // A trace acknowledgement without the header comes from a receiver that predates
+                    // placeholders, whatever the request carried: live spans stop, before any placeholder
+                    // reaches a receiver that acknowledged completed spans first.
+                    if (this.signal === "traces" && !acceptsPlaceholders)
+                        this.transport.rejectPlaceholders(placeholders ? count : 0);
+                    if (placeholders) {
+                        // Placeholders travel alone, so the count is theirs: a warning, never a loss. A
+                        // receiver with the header never rejects a placeholder for being one.
+                        if (acceptsPlaceholders && (count || partial?.errorMessage))
+                            this.transport.issue(this.signal, "warning", count, count
+                                ? "Hue rejected in-progress span placeholders"
+                                : "Hue returned an ingestion warning");
+                        return {};
+                    }
+                    // Completed records travel alone too, so the count is theirs in full. Rejections are
+                    // not matched to records: a rejection of spans in a batch of one trace is that trace's;
+                    // in a batch of several it names none, since the innocent traces' spans may have been
+                    // accepted, and each case's receipt decides. A rejection of log records names every
+                    // trace in the batch: the receipt counts spans, not logs, so it could not tell whose
+                    // logs were lost.
+                    rejected = count;
                     const rejectedTraceIds = this.signal === "logs" || (traceIds && traceIds.length === 1) ? traceIds : undefined;
-                    if (remaining || (partial?.errorMessage && !downgrade))
-                        this.transport.issue(this.signal, rejected ? "rejected" : "warning", rejected || remaining, rejected
+                    if (count || partial?.errorMessage)
+                        this.transport.issue(this.signal, count ? "rejected" : "warning", count, count
                             ? "Hue rejected telemetry records; inspect the project ingestion settings and supported limits"
-                            : remaining
-                                ? "Hue rejected in-progress span placeholders"
-                                : "Hue returned an ingestion warning", undefined, rejectedTraceIds);
+                            : "Hue returned an ingestion warning", undefined, rejectedTraceIds);
                     // Do not pass backend error text or raw response bytes into the global OTel diagnostic logger.
                     return {};
                 }

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.12.1";
+export declare const sdkVersion = "0.13.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.12.1";
+export const sdkVersion = "0.13.1";

package/package.json

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