@remit/logger-lambda 0.0.11 → 0.0.13

package/README.md

@@ -92,5 +92,5 @@ one adds to the bindings of the one it runs inside.
 | -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | `LOG_LEVEL`          | `info`  | `trace`, `debug`, `info`, `warn`, `error`, `fatal` or `silent`. An unrecognised value logs one warning and falls back to the default. |
 | `REMIT_SERVICE_NAME` | `remit` | The `service` field on every line. Stamped into each service bundle at build time by `npm-scripts/docker-bundle.mjs`.                 |
-| `METRICS_PORT`       | `9464`  | Port `startMetricsServer` binds. |
+| `METRICS_PORT`       | `9464`  | Port `startMetricsServer` binds. Empty is unset and takes the default; anything that is not a port number in 0–65535 logs one error and serves no metrics, rather than falling back. A service that cannot be scraped is a smaller failure than one that reports on the wrong port. |
 | `METRICS_HOST`       | `0.0.0.0` | Interface `startMetricsServer` binds. Set `127.0.0.1` when the service runs as a host process rather than a container. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/logger-lambda",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",

package/src/log-output.test.ts

@@ -28,7 +28,9 @@ process.stdout.write = ((
 	return (originalWrite as (...args: unknown[]) => boolean)(chunk, ...rest);
 }) as typeof process.stdout.write;
 
-const { createLogger, logger, withLogContext } = await import("./logger.js");
+const { createLogger, logger, withLogContext, withTelemetry } = await import(
+	"./logger.js"
+);
 
 const parse = (): Line[] =>
 	written
@@ -353,3 +355,76 @@ describe("withLogContext", () => {
 		assert.equal(repeats.length, 1);
 	});
 });
+
+describe("withTelemetry", () => {
+	const context = {
+		awsRequestId: "req-1",
+		functionName: "test-function",
+	} as unknown as Parameters<Parameters<typeof withTelemetry>[0]>[1];
+
+	it("puts its own start line inside the scope", async () => {
+		const lines = await captureAsync(async () => {
+			await withTelemetry(async () => "ok")({}, context);
+		});
+		const started = lines.find(
+			(line) => line.msg === "Lambda invocation started",
+		);
+		assert.ok(started, "expected the start line");
+		assert.equal(started.requestId, "req-1");
+	});
+
+	// The line an operator correlates from is written after the handler has
+	// unwound, which is exactly what a scope opened inside the handler misses.
+	it("puts its own failure line inside the scope", async () => {
+		const lines = await captureAsync(async () => {
+			await assert.rejects(
+				withTelemetry(async () => {
+					throw new Error("boom");
+				})({}, context),
+			);
+		});
+		const failed = lines.find(
+			(line) => line.msg === "Lambda invocation failed",
+		);
+		assert.ok(failed, "expected the failure line");
+		assert.equal(failed.requestId, "req-1");
+	});
+
+	it("carries the same requestId onto the handler's own lines", async () => {
+		const lines = await captureAsync(async () => {
+			await withTelemetry(async () => {
+				logger.warn("from the handler");
+				return "ok";
+			})({}, context);
+		});
+		assert.deepEqual(
+			[...new Set(lines.map((line) => line.requestId))],
+			["req-1"],
+		);
+	});
+
+	it("keeps concurrent invocations apart", async () => {
+		const invoke = (id: string, delayMs: number) =>
+			withTelemetry(async () => {
+				await new Promise((resolve) => setTimeout(resolve, delayMs));
+				logger.warn(`handled ${id}`);
+			})({}, {
+				awsRequestId: id,
+				functionName: "test-function",
+			} as unknown as typeof context);
+
+		const lines = await captureAsync(async () => {
+			await Promise.all([invoke("slow", 10), invoke("fast", 1)]);
+		});
+
+		assert.deepEqual(
+			lines
+				.filter((line) => String(line.msg).startsWith("handled "))
+				.map((line) => [line.msg, line.requestId]),
+			[
+				["handled fast", "fast"],
+				["handled slow", "slow"],
+			],
+		);
+	});
+});

package/src/logger.ts

@@ -159,32 +159,38 @@ export const logger: Logger = createAdapter(root, {});
 
 export const createLogger = (): Logger => createAdapter(root, {});
 
+// The scope opens around the wrapper's own two lines, not just the handler:
+// "Lambda invocation failed" is the line an operator correlates from, and it is
+// written after the handler has already unwound, so a scope opened inside the
+// handler no longer covers it. Everything the invocation writes — the wrapper's
+// lines and the handler's — carries the same `requestId`.
 export const withTelemetry = <TEvent, TResult>(
 	handler: (event: TEvent, context: Context) => Promise<TResult>,
 ): ((event: TEvent, context: Context) => Promise<TResult>) => {
-	return async (event: TEvent, context: Context): Promise<TResult> => {
-		logger.debug("Lambda invocation started", {
-			functionName: context.functionName,
-		});
-
-		const start = Date.now();
-
-		try {
-			const result = await handler(event, context);
-			recordHandlerOutcome({
-				handler: context.functionName,
-				outcome: "success",
-				durationMs: Date.now() - start,
-			});
-			return result;
-		} catch (err) {
-			recordHandlerOutcome({
-				handler: context.functionName,
-				outcome: "failure",
-				durationMs: Date.now() - start,
+	return async (event: TEvent, context: Context): Promise<TResult> =>
+		withLogContext({ requestId: context.awsRequestId }, async () => {
+			logger.debug("Lambda invocation started", {
+				functionName: context.functionName,
 			});
-			logger.error("Lambda invocation failed", { error: err });
-			throw err;
-		}
-	};
+
+			const start = Date.now();
+
+			try {
+				const result = await handler(event, context);
+				recordHandlerOutcome({
+					handler: context.functionName,
+					outcome: "success",
+					durationMs: Date.now() - start,
+				});
+				return result;
+			} catch (err) {
+				recordHandlerOutcome({
+					handler: context.functionName,
+					outcome: "failure",
+					durationMs: Date.now() - start,
+				});
+				logger.error("Lambda invocation failed", { error: err });
+				throw err;
+			}
+		});
 };

package/src/metrics.test.ts

@@ -1,4 +1,5 @@
 import assert from "node:assert/strict";
+import type { Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import { afterEach, beforeEach, describe, it } from "node:test";
 import {
@@ -402,4 +403,80 @@ describe("the /metrics endpoint", () => {
 		delete process.env.METRICS_PORT;
 		assert.ok((server.address() as AddressInfo).port > 0);
 	});
+
+	const startWithMetricsPort = (value: string, reported: Error[]) => {
+		process.env.METRICS_PORT = value;
+		try {
+			return startMetricsServer({
+				host: "127.0.0.1",
+				onError: (error) => reported.push(error),
+			});
+		} finally {
+			delete process.env.METRICS_PORT;
+		}
+	};
+
+	for (const value of ["nine-thousand", "99999", "-1", "9464.5"]) {
+		it(`refuses to bind METRICS_PORT=${value} instead of taking the worker down`, () => {
+			const reported: Error[] = [];
+			const server = startWithMetricsPort(value, reported);
+			assert.equal(server.listening, false);
+			assert.equal(reported.length, 1);
+			assert.match(reported[0].message, /METRICS_PORT/);
+			assert.ok(reported[0].message.includes(value));
+		});
+	}
+
+	it("treats a blank METRICS_PORT as unconfigured", async () => {
+		const reported: Error[] = [];
+		const server = startWithMetricsPort("  ", reported);
+		servers.push(server);
+		const bound = await new Promise<boolean>((resolve) => {
+			server.once("listening", () => resolve(true));
+			server.once("error", () => resolve(false));
+		});
+		if (!bound) {
+			// 9464 is already taken on this host, which is itself proof the
+			// fallback resolved to it: an ephemeral port is never in use.
+			assert.match(String(reported[0]), /EADDRINUSE/);
+			return;
+		}
+		assert.deepEqual(reported, []);
+		assert.equal((server.address() as AddressInfo).port, DEFAULT_METRICS_PORT);
+	});
+
+	it("refuses an out-of-range port passed by a caller", () => {
+		const reported: Error[] = [];
+		const server = startMetricsServer({
+			port: 70000,
+			host: "127.0.0.1",
+			onError: (error) => reported.push(error),
+		});
+		assert.equal(server.listening, false);
+		assert.equal(reported.length, 1);
+		assert.match(reported[0].message, /70000/);
+	});
+
+	it("reports a malformed port as one JSON line on stderr by default", () => {
+		const written: string[] = [];
+		const restore = process.stderr.write.bind(process.stderr);
+		process.env.METRICS_PORT = "not-a-port";
+		process.stderr.write = ((chunk: string) => {
+			written.push(String(chunk));
+			return true;
+		}) as typeof process.stderr.write;
+		let server: Server;
+		try {
+			server = startMetricsServer({ host: "127.0.0.1" });
+		} finally {
+			process.stderr.write = restore;
+			delete process.env.METRICS_PORT;
+		}
+
+		assert.equal(server.listening, false);
+		assert.equal(written.length, 1);
+		const line = JSON.parse(written[0]) as { level: string; error: string };
+		assert.equal(line.level, "error");
+		assert.match(line.error, /not-a-port/);
+	});
 });

package/src/metrics.ts

@@ -230,6 +230,31 @@ const reportToStderr = (error: Error): void => {
 	);
 };
 
+const MAX_PORT = 65535;
+
+const isBindablePort = (port: number): boolean =>
+	Number.isInteger(port) && port >= 0 && port <= MAX_PORT;
+
+// `listen` rejects anything outside 0..65535 by throwing ERR_SOCKET_BAD_PORT
+// synchronously, which the `'error'` handler never sees. A blank value is a
+// variable someone left empty rather than a request for port 0, so it reads as
+// unset; anything else that does not parse is a typo worth naming.
+const configuredPort = (override: number | undefined): number | Error => {
+	if (override !== undefined) {
+		return isBindablePort(override)
+			? override
+			: new Error(`not a port number: ${override}`);
+	}
+	const configured = (process.env.METRICS_PORT ?? "").trim();
+	if (configured === "") {
+		return DEFAULT_METRICS_PORT;
+	}
+	const parsed = Number(configured);
+	return isBindablePort(parsed)
+		? parsed
+		: new Error(`METRICS_PORT is not a port number: ${configured}`);
+};
+
 /**
  * The listener D2 adds to each worker image, for `/metrics` alone. Bound to the
  * compose network and never published to the host: the only host ports in the
@@ -239,8 +264,10 @@ const reportToStderr = (error: Error): void => {
  * later tick, by which time the poll loop is already running, so an unhandled
  * `'error'` event here would kill a worker in the middle of syncing mail —
  * 9464 is the OpenTelemetry Prometheus exporter's default, so a collector on
- * the same host is a real trigger. An observability endpoint must never be able
- * to stop mail from arriving; absent metrics are the correct failure.
+ * the same host is a real trigger. A port that is not a port at all is refused
+ * the same way, before `listen` can throw it at the caller. An observability
+ * endpoint must never be able to stop mail from arriving; absent metrics are
+ * the correct failure.
  *
  * Unreferenced from the event loop, so it never keeps a worker alive past the
  * end of its poll loop.
@@ -248,14 +275,18 @@ const reportToStderr = (error: Error): void => {
 export const startMetricsServer = (
 	options: MetricsServerOptions = {},
 ): Server => {
-	const port =
-		options.port ??
-		Number(process.env.METRICS_PORT ?? String(DEFAULT_METRICS_PORT));
 	const host = options.host ?? process.env.METRICS_HOST ?? "0.0.0.0";
 	const onError = options.onError ?? reportToStderr;
 	const server = createServer(createMetricsRequestListener());
 	server.unref();
 	server.on("error", onError);
+
+	const port = configuredPort(options.port);
+	if (port instanceof Error) {
+		onError(port);
+		return server;
+	}
+
 	server.listen(port, host);
 	return server;
 };