@allthings/cloud-toolkit 5.4.0-beta.1 → 5.4.0-beta.2

package/README.md

@@ -125,7 +125,7 @@ Global `fetch` (undici) and `http`/`https` calls are traced automatically.
 Configuration (environment):
 
 - `OTEL_ENABLED=true` — turns tracing on; otherwise every function is a pass-through.
-- Lambda `tracing: Active` — provides `AWS_XRAY_DAEMON_ADDRESS`; spans go there as OTLP over UDP (no layer, no added latency). Without it, spans go via OTLP/HTTP to `OTEL_EXPORTER_OTLP_*` (default `localhost:4318`).
+- Lambda `tracing: Active` — provides `AWS_XRAY_DAEMON_ADDRESS`; spans go there as OTLP over UDP (no layer; a send only waits for the local socket write, and `withInvocationSpan` waits at most 2.5 s for the flush before returning). Without it, spans go via OTLP/HTTP to `OTEL_EXPORTER_OTLP_*` (default `localhost:4318`).
 - `OTEL_SERVICE_NAME` — optional, defaults to `AWS_LAMBDA_FUNCTION_NAME`.
 
 The SDK starts when the module is first imported, so import it before modules that load `http`/`https`.

package/dist/src/tracing/index.d.ts

@@ -1,2 +1,2 @@
-export { createOtlpUdpSpanExporter } from './otlpUdpSpanExporter';
+export { createOtlpUdpSpanExporter, IOtlpUdpSpanExporterOptions, } from './otlpUdpSpanExporter';
 export { createTracingSdk, ITracingSdk, ITracingSdkOptions, TSpanAttributes, withInvocationSpan, withStageSpan, } from './tracing';

package/dist/src/tracing/otlpUdpSpanExporter.d.ts

@@ -1,2 +1,5 @@
 import { SpanExporter } from '@opentelemetry/sdk-trace-node';
-export declare const createOtlpUdpSpanExporter: (endpoint?: string) => SpanExporter;
+export interface IOtlpUdpSpanExporterOptions {
+    maxPayloadBytes?: number;
+}
+export declare const createOtlpUdpSpanExporter: (endpoint?: string, { maxPayloadBytes }?: IOtlpUdpSpanExporterOptions) => SpanExporter;

package/dist/tracing.cjs.js

@@ -18,6 +18,7 @@ const DEFAULT_ENDPOINT = '127.0.0.1:2000';
 const PROTOCOL_HEADER = '{"format":"json","version":1}\n';
 const OTEL_TRACES_BINARY_PREFIX = 'T1S';
 const MAX_PORT = 65_535;
+const MAX_UDP_PAYLOAD_BYTES = 65_507;
 const parseEndpoint = (endpoint) => {
     const [host, port] = endpoint.split(':');
     const parsedPort = Number(port);
@@ -30,37 +31,60 @@ const parseEndpoint = (endpoint) => {
     }
     return { host, port: parsedPort };
 };
-const reportFailure = (error, resultCallback) => {
-    api.diag.error('Error sending OTLP/UDP data: %s', error);
-    resultCallback({ code: core.ExportResultCode.FAILED, error });
+const encode = (spans) => {
+    const serialized = otlpTransformer.ProtobufTraceSerializer.serializeRequest(spans);
+    return serialized == null
+        ? undefined
+        : Buffer.from(`${PROTOCOL_HEADER}${OTEL_TRACES_BINARY_PREFIX}${Buffer.from(serialized).toString('base64')}`, 'utf8');
 };
-const sendMessage = (socket, message, { host, port }, resultCallback) => {
+const encodeBatches = (spans, maxPayloadBytes) => {
+    const message = encode(spans);
+    if (!message) {
+        return { droppedSpans: 0, messages: [] };
+    }
+    if (message.length <= maxPayloadBytes) {
+        return { droppedSpans: 0, messages: [message] };
+    }
+    if (spans.length === 1) {
+        return { droppedSpans: 1, messages: [] };
+    }
+    const middle = Math.ceil(spans.length / 2);
+    const head = encodeBatches(spans.slice(0, middle), maxPayloadBytes);
+    const tail = encodeBatches(spans.slice(middle), maxPayloadBytes);
+    return {
+        droppedSpans: head.droppedSpans + tail.droppedSpans,
+        messages: [...head.messages, ...tail.messages],
+    };
+};
+const send = (socket, message, { host, port }) => new Promise((resolve) => {
     try {
-        socket.send(Buffer.from(message, 'utf8'), port, host, (error) => {
-            if (error) {
-                reportFailure(error, resultCallback);
-                return;
-            }
-            resultCallback({ code: core.ExportResultCode.SUCCESS });
+        socket.send(message, port, host, (error) => {
+            resolve(error ?? undefined);
         });
     }
     catch (error) {
-        reportFailure(error instanceof Error ? error : new Error(String(error)), resultCallback);
+        resolve(error instanceof Error ? error : new Error(String(error)));
     }
+});
+const exportBatches = async (socket, endpoint, { droppedSpans, messages }) => {
+    const errors = await Promise.all(messages.map((message) => send(socket, message, endpoint)));
+    const error = errors.find((sendError) => sendError !== undefined) ??
+        (droppedSpans > 0
+            ? new Error(`${droppedSpans} span(s) exceed the UDP payload limit`)
+            : undefined);
+    if (error) {
+        api.diag.error('Error sending OTLP/UDP data: %s', error);
+        return { code: core.ExportResultCode.FAILED, error };
+    }
+    return { code: core.ExportResultCode.SUCCESS };
 };
-const createOtlpUdpSpanExporter = (endpoint = DEFAULT_ENDPOINT) => {
-    const { host, port } = parseEndpoint(endpoint);
+const createOtlpUdpSpanExporter = (endpoint = DEFAULT_ENDPOINT, { maxPayloadBytes = MAX_UDP_PAYLOAD_BYTES } = {}) => {
+    const parsedEndpoint = parseEndpoint(endpoint);
     const socket = dgram.createSocket('udp4');
     socket.unref();
     return {
         export: (spans, resultCallback) => {
-            const serialized = otlpTransformer.ProtobufTraceSerializer.serializeRequest(spans);
-            if (serialized == null) {
-                resultCallback({ code: core.ExportResultCode.SUCCESS });
-                return;
-            }
-            const message = `${PROTOCOL_HEADER}${OTEL_TRACES_BINARY_PREFIX}${Buffer.from(serialized).toString('base64')}`;
-            sendMessage(socket, message, { host, port }, resultCallback);
+            void exportBatches(socket, parsedEndpoint, encodeBatches(spans, maxPayloadBytes)).then(resultCallback);
         },
         forceFlush: () => Promise.resolve(),
         shutdown: () => new Promise((resolve) => {
@@ -101,22 +125,26 @@ const sdk = process.env.OTEL_ENABLED === 'true' ? createTracingSdk() : undefined
 const invocationParentContext = () => api.propagation.extract(api.context.active(), {
     'x-amzn-trace-id': process.env._X_AMZN_TRACE_ID ?? '',
 });
-const finishSpan = (span, error) => {
-    if (error instanceof Error) {
-        span.recordException(error);
-        span.setStatus({ code: api.SpanStatusCode.ERROR, message: error.message });
-    }
+const failSpan = (span, error) => {
+    const exception = error instanceof Error ? error : new Error(String(error));
+    span.recordException(exception);
+    span.setStatus({ code: api.SpanStatusCode.ERROR, message: exception.message });
     span.end();
 };
 const logFlushFailure = () => {
     console.warn('OTel span flush failed');
 };
-const flushWithBudget = (flush) => Promise.race([
-    Promise.resolve().then(flush).catch(logFlushFailure),
-    new Promise((resolve) => {
-        setTimeout(resolve, FLUSH_BUDGET_MS).unref();
-    }),
-]);
+const flushWithBudget = (flush) => new Promise((resolve) => {
+    const budget = setTimeout(resolve, FLUSH_BUDGET_MS);
+    budget.unref();
+    void Promise.resolve()
+        .then(flush)
+        .catch(logFlushFailure)
+        .finally(() => {
+        clearTimeout(budget);
+        resolve();
+    });
+});
 const getStatusCode = (result) => {
     if (typeof result !== 'object' || result === null) {
         return undefined;
@@ -139,11 +167,11 @@ const withInvocationSpan = async (attributes, run) => {
         if (statusCode !== undefined && statusCode >= 500) {
             span.setStatus({ code: api.SpanStatusCode.ERROR });
         }
-        finishSpan(span);
+        span.end();
         return result;
     }
     catch (error) {
-        finishSpan(span, error);
+        failSpan(span, error);
         throw error;
     }
     finally {
@@ -157,11 +185,11 @@ const withStageSpan = async (name, run) => {
     return sdk.tracer.startActiveSpan(name, async (span) => {
         try {
             const result = await run();
-            finishSpan(span);
+            span.end();
             return result;
         }
         catch (error) {
-            finishSpan(span, error);
+            failSpan(span, error);
             throw error;
         }
     });

package/dist/tracing.esm.mjs

@@ -16,6 +16,7 @@ const DEFAULT_ENDPOINT = '127.0.0.1:2000';
 const PROTOCOL_HEADER = '{"format":"json","version":1}\n';
 const OTEL_TRACES_BINARY_PREFIX = 'T1S';
 const MAX_PORT = 65_535;
+const MAX_UDP_PAYLOAD_BYTES = 65_507;
 const parseEndpoint = (endpoint) => {
     const [host, port] = endpoint.split(':');
     const parsedPort = Number(port);
@@ -28,37 +29,60 @@ const parseEndpoint = (endpoint) => {
     }
     return { host, port: parsedPort };
 };
-const reportFailure = (error, resultCallback) => {
-    diag.error('Error sending OTLP/UDP data: %s', error);
-    resultCallback({ code: ExportResultCode.FAILED, error });
+const encode = (spans) => {
+    const serialized = ProtobufTraceSerializer.serializeRequest(spans);
+    return serialized == null
+        ? undefined
+        : Buffer.from(`${PROTOCOL_HEADER}${OTEL_TRACES_BINARY_PREFIX}${Buffer.from(serialized).toString('base64')}`, 'utf8');
 };
-const sendMessage = (socket, message, { host, port }, resultCallback) => {
+const encodeBatches = (spans, maxPayloadBytes) => {
+    const message = encode(spans);
+    if (!message) {
+        return { droppedSpans: 0, messages: [] };
+    }
+    if (message.length <= maxPayloadBytes) {
+        return { droppedSpans: 0, messages: [message] };
+    }
+    if (spans.length === 1) {
+        return { droppedSpans: 1, messages: [] };
+    }
+    const middle = Math.ceil(spans.length / 2);
+    const head = encodeBatches(spans.slice(0, middle), maxPayloadBytes);
+    const tail = encodeBatches(spans.slice(middle), maxPayloadBytes);
+    return {
+        droppedSpans: head.droppedSpans + tail.droppedSpans,
+        messages: [...head.messages, ...tail.messages],
+    };
+};
+const send = (socket, message, { host, port }) => new Promise((resolve) => {
     try {
-        socket.send(Buffer.from(message, 'utf8'), port, host, (error) => {
-            if (error) {
-                reportFailure(error, resultCallback);
-                return;
-            }
-            resultCallback({ code: ExportResultCode.SUCCESS });
+        socket.send(message, port, host, (error) => {
+            resolve(error ?? undefined);
         });
     }
     catch (error) {
-        reportFailure(error instanceof Error ? error : new Error(String(error)), resultCallback);
+        resolve(error instanceof Error ? error : new Error(String(error)));
     }
+});
+const exportBatches = async (socket, endpoint, { droppedSpans, messages }) => {
+    const errors = await Promise.all(messages.map((message) => send(socket, message, endpoint)));
+    const error = errors.find((sendError) => sendError !== undefined) ??
+        (droppedSpans > 0
+            ? new Error(`${droppedSpans} span(s) exceed the UDP payload limit`)
+            : undefined);
+    if (error) {
+        diag.error('Error sending OTLP/UDP data: %s', error);
+        return { code: ExportResultCode.FAILED, error };
+    }
+    return { code: ExportResultCode.SUCCESS };
 };
-const createOtlpUdpSpanExporter = (endpoint = DEFAULT_ENDPOINT) => {
-    const { host, port } = parseEndpoint(endpoint);
+const createOtlpUdpSpanExporter = (endpoint = DEFAULT_ENDPOINT, { maxPayloadBytes = MAX_UDP_PAYLOAD_BYTES } = {}) => {
+    const parsedEndpoint = parseEndpoint(endpoint);
     const socket = dgram.createSocket('udp4');
     socket.unref();
     return {
         export: (spans, resultCallback) => {
-            const serialized = ProtobufTraceSerializer.serializeRequest(spans);
-            if (serialized == null) {
-                resultCallback({ code: ExportResultCode.SUCCESS });
-                return;
-            }
-            const message = `${PROTOCOL_HEADER}${OTEL_TRACES_BINARY_PREFIX}${Buffer.from(serialized).toString('base64')}`;
-            sendMessage(socket, message, { host, port }, resultCallback);
+            void exportBatches(socket, parsedEndpoint, encodeBatches(spans, maxPayloadBytes)).then(resultCallback);
         },
         forceFlush: () => Promise.resolve(),
         shutdown: () => new Promise((resolve) => {
@@ -99,22 +123,26 @@ const sdk = process.env.OTEL_ENABLED === 'true' ? createTracingSdk() : undefined
 const invocationParentContext = () => propagation.extract(context.active(), {
     'x-amzn-trace-id': process.env._X_AMZN_TRACE_ID ?? '',
 });
-const finishSpan = (span, error) => {
-    if (error instanceof Error) {
-        span.recordException(error);
-        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
-    }
+const failSpan = (span, error) => {
+    const exception = error instanceof Error ? error : new Error(String(error));
+    span.recordException(exception);
+    span.setStatus({ code: SpanStatusCode.ERROR, message: exception.message });
     span.end();
 };
 const logFlushFailure = () => {
     console.warn('OTel span flush failed');
 };
-const flushWithBudget = (flush) => Promise.race([
-    Promise.resolve().then(flush).catch(logFlushFailure),
-    new Promise((resolve) => {
-        setTimeout(resolve, FLUSH_BUDGET_MS).unref();
-    }),
-]);
+const flushWithBudget = (flush) => new Promise((resolve) => {
+    const budget = setTimeout(resolve, FLUSH_BUDGET_MS);
+    budget.unref();
+    void Promise.resolve()
+        .then(flush)
+        .catch(logFlushFailure)
+        .finally(() => {
+        clearTimeout(budget);
+        resolve();
+    });
+});
 const getStatusCode = (result) => {
     if (typeof result !== 'object' || result === null) {
         return undefined;
@@ -137,11 +165,11 @@ const withInvocationSpan = async (attributes, run) => {
         if (statusCode !== undefined && statusCode >= 500) {
             span.setStatus({ code: SpanStatusCode.ERROR });
         }
-        finishSpan(span);
+        span.end();
         return result;
     }
     catch (error) {
-        finishSpan(span, error);
+        failSpan(span, error);
         throw error;
     }
     finally {
@@ -155,11 +183,11 @@ const withStageSpan = async (name, run) => {
     return sdk.tracer.startActiveSpan(name, async (span) => {
         try {
             const result = await run();
-            finishSpan(span);
+            span.end();
             return result;
         }
         catch (error) {
-            finishSpan(span, error);
+            failSpan(span, error);
             throw error;
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allthings/cloud-toolkit",
-  "version": "5.4.0-beta.1",
+  "version": "5.4.0-beta.2",
   "description": "",
   "author": "Allthings GmbH",
   "keywords": [