@hue-run/sdk 0.11.3 → 0.12.0

package/dist/transport.js

@@ -138,12 +138,13 @@ export class HueTransport {
                     if (!queued)
                         return;
                     admitted = queued;
+                    this.countEnded(admitted);
                     spans.onEnd(admitted);
                 }
                 catch {
                     if (admitted)
                         this.finish("traces", [admitted]);
-                    this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record");
+                    this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record", undefined, traceIdsOf([span]));
                 }
             },
             forceFlush: () => spans.forceFlush(),
@@ -165,7 +166,7 @@ export class HueTransport {
                 catch {
                     if (admitted)
                         this.finish("logs", [admitted]);
-                    this.issue("logs", "invalid", 1, "Telemetry processor could not accept a record");
+                    this.issue("logs", "invalid", 1, "Telemetry processor could not accept a record", undefined, traceIdsOf([log]));
                 }
             },
             forceFlush: () => logs.forceFlush(),
@@ -181,10 +182,13 @@ export class HueTransport {
         const pending = signal === "traces" ? this.spans : this.logs;
         if (advisory && (this.closed || pending.size >= 2048 / 4))
             return undefined;
+        // A record dropped here names its trace, so a runner with several traces in flight knows
+        // whose telemetry is missing; a log record names the trace of the span it was emitted in.
+        const traceIds = traceIdsOf([record]);
         if (this.closed || pending.size >= 2048) {
             this.issue(signal, "dropped", 1, this.closed
                 ? "Telemetry emitted after transport shutdown"
-                : "Telemetry queue reached 2048 records");
+                : "Telemetry queue reached 2048 records", undefined, traceIds);
             return undefined;
         }
         try {
@@ -205,7 +209,7 @@ export class HueTransport {
         catch {
             if (advisory)
                 return undefined;
-            this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data");
+            this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data", undefined, traceIds);
             return undefined;
         }
     }
@@ -299,7 +303,7 @@ export class HueTransport {
         this.accepted[signal] += count;
     }
     /** @internal Records a sanitized issue, updates counters and rate-limits the diagnostic callback. */
-    issue(signal, kind, count, message, status) {
+    issue(signal, kind, count, message, status, traceIds) {
         if (kind === "dropped")
             this.dropped[signal] += count;
         if (kind === "rejected")
@@ -313,6 +317,7 @@ export class HueTransport {
             count,
             message,
             ...(status !== undefined ? { status } : {}),
+            ...(traceIds !== undefined ? { traceIds } : {}),
         };
         if (kind !== "warning")
             this.failureSequence = issue.sequence;
@@ -339,11 +344,13 @@ export class HueTransport {
         }
     }
     /** @internal Counts a helper capture or instrumentation failure that preserved application execution. */
-    instrumentationFailure(signal = "traces", message = "Telemetry capture or instrumentation failed; application execution was preserved", count = 1) {
+    /** Records a capture or instrumentation failure, named to the trace it happened in when the
+     * caller knows it, so a runner with several traces in flight can tell whose it was. */
+    instrumentationFailure(signal = "traces", message = "Telemetry capture or instrumentation failed; application execution was preserved", count = 1, traceId) {
         if (!Number.isSafeInteger(count) || count < 1)
             return;
         this.instrumentationFailures += count;
-        this.issue(signal, "invalid", 0, message);
+        this.issue(signal, "invalid", 0, message, undefined, traceId ? [traceId] : undefined);
     }
     /** Cumulative counters and current queue gauges. */
     getReport() {
@@ -370,6 +377,26 @@ export class HueTransport {
     getFailureSequence() {
         return this.failureSequence;
     }
+    /** Spans of a trace this transport has handed to its exporter, by trace id, for the newest
+     * traces only: a runner compares the count with the trace receipt's span count to know that
+     * every span of a case landed, not only the root. Undefined for a trace it does not remember,
+     * which is not the same as none: the caller must not take an unknown count for complete. */
+    spansEnded(traceId) {
+        return this.endedSpans.get(traceId);
+    }
+    endedSpans = new Map();
+    countEnded(span) {
+        let traceId;
+        try {
+            traceId = span.spanContext().traceId;
+        }
+        catch {
+            return;
+        }
+        this.endedSpans.set(traceId, (this.endedSpans.get(traceId) ?? 0) + 1);
+        if (this.endedSpans.size > MAX_REMEMBERED_TRACES)
+            this.endedSpans.delete(this.endedSpans.keys().next().value);
+    }
     /**
      * Waits for the processors' and exporters' in-flight work; drain the providers first.
      *
@@ -427,6 +454,32 @@ export class HueTransport {
         return this.shutdownPromise;
     }
 }
+/** The distinct trace ids of a batch, or undefined past 64 of them, when an issue would name too
+ * many traces to tell one apart; a record whose context cannot be read is left out. */
+const MAX_ISSUE_TRACE_IDS = 64;
+/** How many traces' ended-span counts one transport remembers; the oldest is forgotten first. */
+const MAX_REMEMBERED_TRACES = 10_000;
+function traceIdsOf(records) {
+    const ids = new Set();
+    for (const record of records) {
+        try {
+            // A span reports its context; a log record carries the span's identifiers.
+            const traceId = "spanContext" in record && typeof record.spanContext === "function"
+                ? record.spanContext().traceId
+                : record.spanContext?.traceId;
+            if (traceId)
+                ids.add(traceId);
+        }
+        catch {
+            // A record without a readable context names no trace.
+        }
+        if (ids.size > MAX_ISSUE_TRACE_IDS)
+            return undefined;
+    }
+    // No readable trace names nobody, which is not the same as naming no one's: the issue may
+    // concern any trace in flight.
+    return ids.size ? [...ids] : undefined;
+}
 class ReportingExporter {
     transport;
     signal;
@@ -485,12 +538,12 @@ class ReportingExporter {
         const cache = new WeakMap();
         let failed = false;
         let redactedBytes = 0;
-        const invalid = (placeholder, message) => {
+        const invalid = (placeholder, message, record) => {
             if (placeholder)
                 this.transport.issue(this.signal, "warning", 1, `${message} (in-progress span placeholder)`);
             else {
                 failed = true;
-                this.transport.issue(this.signal, "invalid", 1, message);
+                this.transport.issue(this.signal, "invalid", 1, message, undefined, record ? traceIdsOf([record]) : undefined);
             }
         };
         const send = async (batch) => {
@@ -539,7 +592,7 @@ class ReportingExporter {
                     placeholders.add(redacted);
             }
             catch {
-                invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits");
+                invalid(markers !== undefined, "Telemetry record could not be redacted or exceeds supported content limits", record);
             }
         }
         // Each record is encoded once to measure it; a request is encoded once more when it is sent.
@@ -555,7 +608,7 @@ class ReportingExporter {
                 recordBytes = this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
             }
             catch {
-                invalid(placeholders.has(record), "Telemetry record could not be serialized");
+                invalid(placeholders.has(record), "Telemetry record could not be serialized", record);
                 continue;
             }
             const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
@@ -565,7 +618,7 @@ class ReportingExporter {
                 batchBytes = 0;
             }
             if (recordBytes > limit) {
-                invalid(placeholders.has(record), "Telemetry record exceeds the 1 MiB request limit");
+                invalid(placeholders.has(record), "Telemetry record exceeds the 1 MiB request limit", record);
                 continue;
             }
             batch.push(record);
@@ -580,9 +633,12 @@ class ReportingExporter {
     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.
         const lose = (message, status) => {
-            this.transport.issue(this.signal, real ? "failed" : "warning", real || placeholders, real ? message : `${message} (in-progress span placeholders only)`, status);
+            this.transport.issue(this.signal, real ? "failed" : "warning", real || placeholders, real ? message : `${message} (in-progress span placeholders only)`, status, traceIds);
             return !real;
         };
         let rejected = 0;
@@ -611,14 +667,19 @@ class ReportingExporter {
                     if (downgrade)
                         this.transport.rejectPlaceholders(placeholderRejections);
                     const remaining = count - placeholderRejections;
-                    // Rejections are not matched to records. Attribute them to real records first.
+                    // 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);
+                    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
                             ? "Hue rejected telemetry records; inspect the project ingestion settings and supported limits"
                             : remaining
                                 ? "Hue rejected in-progress span placeholders"
-                                : "Hue returned an ingestion warning");
+                                : "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/types.d.ts

@@ -87,6 +87,13 @@ export interface ExportIssue {
     status?: number;
     /** Fixed, sanitized description; never server text or content. */
     message: string;
+    /** The traces the records concerned belonged to, when the issue arose with records in hand
+     * (a refused or rejected batch, a dropped record, a record the processor could not accept, a
+     * capture failure inside a span): up to 64 distinct ids, so a caller running several traces
+     * at once can tell whose telemetry the issue was. Absent for an issue without records (a
+     * processor flush that failed) and for a batch of more traces than that; such an issue may
+     * concern any trace in flight. */
+    traceIds?: string[];
 }
 /** Cumulative delivery counters and current queue gauges for one transport. */
 export interface ExportReport {

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

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

package/package.json

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