@hue-run/sdk 0.1.4 → 0.2.0

package/dist/transport.js

@@ -1,25 +1,68 @@
 import { ExportResultCode } from "@opentelemetry/core";
 import { CompressionAlgorithm, OTLPExporterBase, OTLPExporterError, } from "@opentelemetry/otlp-exporter-base";
-import { convertLegacyHttpOptions, createOtlpHttpExportDelegate, } from "@opentelemetry/otlp-exporter-base/node-http";
+import { createOtlpHttpExportDelegate } from "@opentelemetry/otlp-exporter-base/node-http";
 import { LogsExporterMetricsHelper, ProtobufLogsSerializer, ProtobufTraceSerializer, TraceExporterMetricsHelper, } from "@opentelemetry/otlp-transformer";
 import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace";
 import { BatchLogRecordProcessor, } from "@opentelemetry/sdk-logs";
-import { MAX_BODY_BYTES, validateOptions } from "./config.js";
+import { isInsecureOrigin, MAX_BODY_BYTES, validateOptions } from "./config.js";
+import { estimateRecordBytes } from "./safety.js";
+import { snapshotLog, snapshotSpan } from "./snapshot.js";
 import { redactLog, redactSpan } 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;
+function recordData(record, signal) {
+    if (signal === "traces") {
+        const span = record;
+        return {
+            name: span.name,
+            attributes: span.attributes,
+            events: span.events,
+            links: span.links,
+            status: span.status,
+            resource: span.resource.attributes,
+            scope: span.instrumentationScope,
+        };
+    }
+    const log = record;
+    return {
+        body: log.body,
+        attributes: log.attributes,
+        eventName: log.eventName,
+        severityText: log.severityText,
+        resource: log.resource.attributes,
+        scope: log.instrumentationScope,
+    };
+}
+/**
+ * Rejection of {@link HueClient.flush} and {@link HueClient.shutdown}: telemetry was not fully
+ * accepted. Carries sanitized counts only, never server response text or content.
+ */
 export class HueExportError extends Error {
     issues;
     report;
-    constructor(issues, report) {
+    constructor(
+    /** Non-warning issues observed since the failing drain began. */
+    issues, 
+    /** Cumulative counters and current gauges at the time of the failure. */
+    report) {
         super("Hue could not accept all telemetry. Inspect issues and report for sanitized counts.");
         this.issues = issues;
         this.report = report;
         this.name = "HueExportError";
     }
 }
-/** Owned transport components; attach processors during provider construction. */
+/**
+ * Hue's export pipeline: OTLP/HTTP exporters behind bounded batch processors, with cumulative
+ * counters and a sanitized issue history. A client owns one; in attach mode the application attaches
+ * `spanProcessor` and `logRecordProcessor` to its own providers while constructing them.
+ */
 export class HueTransport {
+    /** Validated options with defaults applied; `baseUrl` is the origin. Not enumerable, so it does not leak the key when logged. */
     options;
+    /** Span processor to attach to a tracer provider; a no-op when disabled. */
     spanProcessor;
+    /** Log record processor to attach to a logger provider; a no-op when disabled. */
     logRecordProcessor;
     sequence = 0;
     observedSequence = 0;
@@ -28,8 +71,13 @@ export class HueTransport {
     accepted = { traces: 0, logs: 0 };
     rejected = { traces: 0, logs: 0 };
     failed = { traces: 0, logs: 0 };
-    spans = new Set();
-    logs = new Set();
+    spans = new Map();
+    logs = new Map();
+    pendingBytes = 0;
+    dropped = { traces: 0, logs: 0 };
+    instrumentationFailures = 0;
+    diagnosticPending = false;
+    lastDiagnosticAt = -Infinity;
     traceExporter;
     logExporter;
     closed = false;
@@ -40,6 +88,13 @@ export class HueTransport {
         Object.defineProperty(this, "options", { enumerable: false });
         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) {
+            this.spanProcessor = { onStart() { }, onEnd() { }, async forceFlush() { }, async shutdown() { } };
+            this.logRecordProcessor = { onEmit() { }, async forceFlush() { }, async shutdown() { } };
+            return;
+        }
+        if (isInsecureOrigin(this.options.baseUrl))
+            this.issue("traces", "warning", 0, "allowInsecureHttp is set: telemetry and the project key are sent over plain HTTP to a host that is not loopback");
         const batching = {
             maxQueueSize: 2048,
             maxExportBatchSize: 128,
@@ -49,22 +104,49 @@ export class HueTransport {
         const spans = new BatchSpanProcessor({ exporter: this.traceExporter, ...batching });
         const logs = new BatchLogRecordProcessor({ exporter: this.logExporter, ...batching });
         this.spanProcessor = {
-            onStart: (span, parent) => spans.onStart(span, parent),
+            onStart: (span, parent) => {
+                try {
+                    spans.onStart(span, parent);
+                }
+                catch {
+                    this.instrumentationFailure();
+                }
+            },
             onEnd: (span) => {
-                if (!(span.spanContext().traceFlags & 1))
-                    return;
-                if (!this.enqueue("traces", span))
-                    return;
-                spans.onEnd(span);
+                let admitted;
+                try {
+                    if (!(span.spanContext().traceFlags & 1))
+                        return;
+                    const queued = this.enqueue("traces", span);
+                    if (!queued)
+                        return;
+                    admitted = queued;
+                    spans.onEnd(admitted);
+                }
+                catch {
+                    if (admitted)
+                        this.finish("traces", [admitted]);
+                    this.issue("traces", "invalid", 1, "Telemetry processor could not accept a record");
+                }
             },
             forceFlush: () => spans.forceFlush(),
             shutdown: () => spans.shutdown(),
         };
         this.logRecordProcessor = {
             onEmit: (log) => {
-                if (!this.enqueue("logs", log))
-                    return;
-                logs.onEmit(log);
+                let admitted;
+                try {
+                    const queued = this.enqueue("logs", log);
+                    if (!queued)
+                        return;
+                    admitted = queued;
+                    logs.onEmit(queued);
+                }
+                catch {
+                    if (admitted)
+                        this.finish("logs", [admitted]);
+                    this.issue("logs", "invalid", 1, "Telemetry processor could not accept a record");
+                }
             },
             forceFlush: () => logs.forceFlush(),
             shutdown: () => logs.shutdown(),
@@ -76,26 +158,43 @@ export class HueTransport {
             this.issue(signal, "dropped", 1, this.closed
                 ? "Telemetry emitted after transport shutdown"
                 : "Telemetry queue reached 2048 records");
-            return false;
+            return undefined;
+        }
+        try {
+            const remaining = this.options.maxQueueBytes - this.pendingBytes;
+            const snapshot = signal === "traces"
+                ? snapshotSpan(record, remaining)
+                : snapshotLog(record, remaining);
+            this.pendingBytes += snapshot.bytes;
+            if (signal === "traces")
+                this.spans.set(snapshot.record, snapshot.bytes);
+            else
+                this.logs.set(snapshot.record, snapshot.bytes);
+            if (snapshot.unresolvedResource)
+                this.issue(signal, "warning", 0, "Unresolved resource attributes omitted from the telemetry snapshot");
+            return snapshot.record;
+        }
+        catch {
+            this.issue(signal, "dropped", 1, "Telemetry snapshot exceeded its byte or complexity budget or contained unsupported data");
+            return undefined;
         }
-        if (signal === "traces")
-            this.spans.add(record);
-        else
-            this.logs.add(record);
-        return true;
     }
+    /** @internal Exporter callback: releases queued records after an export attempt settles. */
     finish(signal, records) {
         for (const record of records) {
-            if (signal === "traces")
-                this.spans.delete(record);
-            else
-                this.logs.delete(record);
+            const pending = signal === "traces" ? this.spans : this.logs;
+            this.pendingBytes -= pending.get(record) ?? 0;
+            pending.delete(record);
         }
     }
+    /** @internal Exporter callback: counts records the collector acknowledged. */
     acceptedRecords(signal, count) {
         this.accepted[signal] += count;
     }
+    /** @internal Records a sanitized issue, updates counters and rate-limits the diagnostic callback. */
     issue(signal, kind, count, message, status) {
+        if (kind === "dropped")
+            this.dropped[signal] += count;
         if (kind === "rejected")
             this.rejected[signal] += count;
         else if (kind !== "warning")
@@ -113,13 +212,31 @@ export class HueTransport {
         this.issues.push(issue);
         if (this.issues.length > 128)
             this.issues.shift();
-        try {
-            this.options.onExportIssue?.({ ...issue });
-        }
-        catch {
-            /* Diagnostics callbacks cannot interrupt the customer's application. */
+        // One diagnostic task at a time, at most once a second. No unbounded promise
+        // queue if a user callback never settles; all issues remain in counts/history.
+        if (this.options.onExportIssue &&
+            !this.diagnosticPending &&
+            Date.now() - this.lastDiagnosticAt >= 1000) {
+            this.diagnosticPending = true;
+            // Warnings (for example the allowInsecureHttp notice) do not consume the slot, so the first
+            // real failure still reaches the callback promptly.
+            if (kind !== "warning")
+                this.lastDiagnosticAt = Date.now();
+            void Promise.resolve()
+                .then(() => this.options.onExportIssue?.({ ...issue }))
+                .then(() => {
+                this.diagnosticPending = false;
+            }, () => {
+                this.diagnosticPending = false;
+            });
         }
     }
+    /** @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") {
+        this.instrumentationFailures++;
+        this.issue(signal, "invalid", 0, message);
+    }
+    /** Cumulative counters and current queue gauges. */
     getReport() {
         return {
             acceptedSpans: this.accepted.traces,
@@ -130,8 +247,13 @@ export class HueTransport {
             failedLogs: this.failed.logs,
             pendingSpans: this.spans.size,
             pendingLogs: this.logs.size,
+            droppedSpans: this.dropped.traces,
+            droppedLogs: this.dropped.logs,
+            pendingBytes: this.pendingBytes,
+            instrumentationFailures: this.instrumentationFailures,
         };
     }
+    /** Copies of the latest 128 sanitized issues, oldest first. */
     getIssues() {
         return this.issues.map((issue) => ({ ...issue }));
     }
@@ -139,6 +261,11 @@ export class HueTransport {
     getFailureSequence() {
         return this.failureSequence;
     }
+    /**
+     * Waits for the processors' and exporters' in-flight work; drain the providers first.
+     *
+     * @throws HueExportError when a new non-warning issue was recorded since the previous observation.
+     */
     flush() {
         const from = this.observedSequence;
         const next = (this.flushPromise ?? Promise.resolve()).then(() => this.flushOnce(from), () => this.flushOnce(from));
@@ -169,6 +296,12 @@ export class HueTransport {
             throw new HueExportError(issues, report);
         return report;
     }
+    /**
+     * Flushes and stops the processors; records emitted afterwards are dropped and counted. In attach
+     * mode call it after shutting down the application's providers.
+     *
+     * @throws HueExportError when the final flush observed new failures.
+     */
     shutdown() {
         this.shutdownPromise ??= (async () => {
             this.closed = true;
@@ -208,40 +341,77 @@ class ReportingExporter {
             .finally(() => {
             this.transport.finish(this.signal, records);
             this.pending.delete(work);
-        });
+        })
+            .catch(() => { });
         this.pending.add(work);
     }
     async exportRecords(records) {
         const accepted = [];
         const cache = new WeakMap();
         let failed = false;
+        let redactedBytes = 0;
+        const resourceDeadline = Date.now() + this.transport.options.timeoutMillis;
         for (const record of records) {
             try {
-                await record.resource.waitForAsyncAttributes?.();
-                accepted.push(this.redact(record, cache));
+                const ready = record.resource.waitForAsyncAttributes?.();
+                if (ready) {
+                    let timer;
+                    try {
+                        await Promise.race([
+                            ready,
+                            new Promise((_resolve, reject) => {
+                                timer = setTimeout(() => reject(new Error("Resource deadline exceeded")), Math.max(1, resourceDeadline - Date.now()));
+                            }),
+                        ]);
+                    }
+                    finally {
+                        clearTimeout(timer);
+                    }
+                }
+                const redacted = this.redact(record, cache);
+                const bytes = 512 +
+                    estimateRecordBytes(recordData(redacted, this.signal), this.transport.options.maxQueueBytes - redactedBytes);
+                if (redactedBytes + bytes > this.transport.options.maxQueueBytes)
+                    throw new RangeError("Redacted batch exceeds byte budget");
+                redactedBytes += bytes;
+                accepted.push(redacted);
             }
             catch {
                 failed = true;
                 this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be redacted or exceeds supported content limits");
             }
         }
+        // Each record is encoded once to measure it; a request is encoded once more when it is sent.
+        // Records sharing a resource and scope are grouped on the wire, so the sum of the individual
+        // 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) {
-            const candidate = [...batch, record];
-            // Leave room for gzip headers/blocks when otherwise incompressible data is near the wire cap.
-            if ((this.serializer.serializeRequest(candidate)?.byteLength ?? 0) <= MAX_BODY_BYTES - 1024) {
-                batch = candidate;
-                continue;
+            let recordBytes;
+            try {
+                recordBytes = this.serializer.serializeRequest([record])?.byteLength ?? Infinity;
             }
-            if (batch.length && !(await this.send(batch)))
+            catch {
                 failed = true;
-            batch = [];
-            if ((this.serializer.serializeRequest([record])?.byteLength ?? 0) > MAX_BODY_BYTES - 1024) {
+                this.transport.issue(this.signal, "invalid", 1, "Telemetry record could not be serialized");
+                continue;
+            }
+            const framedBytes = recordBytes + RECORD_FRAMING_BYTES;
+            if (batch.length && batchBytes + framedBytes > limit) {
+                if (!(await this.send(batch)))
+                    failed = true;
+                batch = [];
+                batchBytes = 0;
+            }
+            if (recordBytes > limit) {
                 failed = true;
                 this.transport.issue(this.signal, "invalid", 1, "Telemetry record exceeds the 1 MiB request limit");
+                continue;
             }
-            else
-                batch = [record];
+            batch.push(record);
+            batchBytes += framedBytes;
         }
         if (batch.length && !(await this.send(batch)))
             failed = true;
@@ -252,9 +422,17 @@ class ReportingExporter {
         const options = this.transport.options;
         let rejected = 0;
         let validResponse = true;
+        let receivedResponse = false;
+        let expired = false;
+        const agents = new Set();
+        const deadline = Date.now() + options.timeoutMillis;
+        let timer;
         const serializer = {
             serializeRequest: (data) => this.serializer.serializeRequest(data),
             deserializeResponse: (bytes) => {
+                if (expired)
+                    return {};
+                receivedResponse = true;
                 try {
                     const response = this.serializer.deserializeResponse(bytes);
                     const partial = response.partialSuccess;
@@ -277,17 +455,46 @@ class ReportingExporter {
             },
         };
         const endpoint = `${options.baseUrl}/api/v1/otlp/v1/${this.signal}`;
-        const delegate = createOtlpHttpExportDelegate(convertLegacyHttpOptions({
+        // Explicit configuration only. OTEL_EXPORTER_OTLP_* environment variables are meant
+        // for generic exporters; merging them here could send another vendor's headers to Hue.
+        const delegate = createOtlpHttpExportDelegate({
             url: endpoint,
-            headers: { Authorization: `Bearer ${options.apiKey}` },
+            headers: async () => ({
+                "Content-Type": "application/x-protobuf",
+                Authorization: `Bearer ${options.apiKey}`,
+            }),
+            // The transport prefixes this to OpenTelemetry's own User-Agent token.
+            userAgent: `hue-sdk-typescript/${sdkVersion}`,
             timeoutMillis: options.timeoutMillis,
             concurrencyLimit: 1,
             compression: CompressionAlgorithm.GZIP,
-        }, this.signal === "traces" ? "TRACES" : "LOGS", `v1/${this.signal}`, { "Content-Type": "application/x-protobuf" }), serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
+            agentFactory: async (protocol) => {
+                if (expired || Date.now() >= deadline)
+                    throw new Error("Hue export deadline exceeded");
+                const { Agent } = await import(protocol === "https:" ? "node:https" : "node:http");
+                const agent = new Agent({ keepAlive: false });
+                agents.add(agent);
+                if (expired)
+                    agent.destroy();
+                return agent;
+            },
+        }, serializer, this.signal === "traces" ? "otlp_http_span_exporter" : "otlp_http_log_exporter", this.metrics, undefined);
         const exporter = new OTLPExporterBase(delegate);
         try {
-            const result = await new Promise((resolve) => exporter.export(records, resolve));
+            const result = await new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    expired = true;
+                    for (const agent of agents)
+                        agent.destroy();
+                    resolve({ code: ExportResultCode.FAILED });
+                }, Math.max(1, deadline - Date.now()));
+                exporter.export(records, resolve);
+            });
             if (result.code === ExportResultCode.SUCCESS) {
+                if (!receivedResponse) {
+                    this.transport.issue(this.signal, "failed", records.length, "Hue response ended without a complete OTLP acknowledgement; acceptance is uncertain");
+                    return false;
+                }
                 if (validResponse)
                     this.transport.acceptedRecords(this.signal, records.length - rejected);
                 return validResponse;
@@ -305,7 +512,12 @@ class ReportingExporter {
             return false;
         }
         finally {
-            await exporter.shutdown();
+            clearTimeout(timer);
+            for (const agent of agents)
+                agent.destroy();
+            // Delegate cleanup cannot extend the hard request wait. Sockets are closed
+            // and the cleanup promise is always observed, even after a caller timeout.
+            void exporter.shutdown().catch(() => { });
         }
     }
     async forceFlush() {
@@ -315,6 +527,12 @@ class ReportingExporter {
         await this.forceFlush();
     }
 }
+/**
+ * Creates the export pipeline for attach mode; pass it with the application's providers to
+ * {@link createHue}. Validates options like an owned client.
+ *
+ * @throws TypeError for invalid options; see {@link createHue}.
+ */
 export function createHueTransport(options) {
     return new HueTransport(options);
 }