@remit/logger-lambda 0.0.9 → 0.0.10

package/README.md

@@ -1,35 +1,26 @@
 # @remit/logger-lambda
 
-Shared logging package for Remit Lambda workers. Wraps [Pino](https://getpino.io/) with Lambda-specific configuration and environment-aware formatting.
+The logging seam every Remit service writes through. One JSON object per line on
+stdout, via [pino](https://getpino.io/). The exported `Logger` interface is what
+consuming code imports; the writer behind it is an implementation detail.
 
-## Features
-
-- **Structured Logging**: JSON output for CloudWatch ingestion in production.
-- **Pretty Print**: Human-readable output for local development.
-- **Request Context**: Automatically correlates logs with Lambda request IDs.
-- **Zero Configuration**: Sensible defaults based on `NODE_ENV`.
-
-## Installation
-
-```bash
-npm install @remit/logger-lambda
-```
+The field names on each line are a contract an operator's log pipeline parses.
+They are documented, with the reserved names and the personal-data caveat, in
+[`deploy/vps/README.md`](../../deploy/vps/README.md) under "Logs".
 
 ## Usage
 
 ```typescript
 import { createLogger } from "@remit/logger-lambda";
-import type { SQSEvent, Context } from "aws-lambda";
+import type { SQSEvent } from "aws-lambda";
 
-export const handler = async (event: SQSEvent, context: Context) => {
-  // Initialize logger with Lambda context
-  const log = createLogger(context);
+const log = createLogger().child({ queue: "remit-imap-sync" });
 
-  log.info({ event }, "Processing SQS event");
+export const handler = async (event: SQSEvent) => {
+  log.debug({ records: event.Records.length }, "Batch received");
 
   try {
     // ... business logic
-    log.info("Success");
   } catch (error) {
     log.error({ error }, "Processing failed");
     throw error;
@@ -37,9 +28,33 @@ export const handler = async (event: SQSEvent, context: Context) => {
 };
 ```
 
-## Environment Variables
+Both argument orders work: `(bindings, message)` and `(message, bindings)`.
+Bindings land at the top level of the line, never nested. A value under `error`
+that is an `Error` is expanded to `type`, `message` and `stack`; anything else is
+written as it is.
+
+`child(bindings)` returns a logger that adds those bindings to every line, and
+`setBindings(bindings)` adds them to an existing one. Neither is per-request:
+they belong to the logger instance, so on a process serving requests
+concurrently use `withLogContext` instead.
+
+```typescript
+import { logger, withLogContext } from "@remit/logger-lambda";
+
+const handler = (request: Request) =>
+  withLogContext({ requestId: request.id }, async () => {
+    logger.debug("Request received"); // carries requestId
+    return respond(request);
+  });
+```
+
+The scope follows the work through its asynchronous continuations, so two
+overlapping requests never see each other's fields. Scopes nest, and an inner
+one adds to the bindings of the one it runs inside.
+
+## Environment variables
 
-| Variable    | Default      | Description                                             |
-| ----------- | ------------ | ------------------------------------------------------- |
-| `LOG_LEVEL` | `info`       | Pino log level (trace, debug, info, warn, error, fatal) |
-| `NODE_ENV`  | `production` | If `development`, enables pretty printing               |
+| Variable             | Default | Description                                                                                                                          |
+| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `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`.                 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/logger-lambda",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -17,9 +17,9 @@
     "build": "npm run test:typecheck"
   },
   "dependencies": {
-    "@aws-lambda-powertools/logger": "^2",
     "@aws-lambda-powertools/metrics": "^2",
-    "@types/aws-lambda": "*"
+    "@types/aws-lambda": "*",
+    "pino": "^10"
   },
   "license": "MIT",
   "publishConfig": {

package/src/log-level.test.ts

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+process.env.LOG_LEVEL = "verbose";
+delete process.env.REMIT_SERVICE_NAME;
+
+type Line = Record<string, unknown>;
+
+const originalWrite = process.stdout.write.bind(process.stdout);
+const written: string[] = [];
+let capturing = true;
+
+process.stdout.write = ((
+	chunk: string | Uint8Array,
+	...rest: unknown[]
+): boolean => {
+	if (capturing && typeof chunk === "string") {
+		written.push(chunk);
+		return true;
+	}
+	return (originalWrite as (...args: unknown[]) => boolean)(chunk, ...rest);
+}) as typeof process.stdout.write;
+
+// Capturing starts before the import: an unusable LOG_LEVEL is reported while
+// the module is evaluated, not on the first call.
+const { createLogger } = await import("./logger.js");
+capturing = false;
+
+const startup = written
+	.join("")
+	.split("\n")
+	.filter((line) => line.length > 0)
+	.map((line) => JSON.parse(line) as Line);
+
+const capture = (emit: () => void): Line[] => {
+	written.length = 0;
+	capturing = true;
+	try {
+		emit();
+	} finally {
+		capturing = false;
+	}
+	return written
+		.join("")
+		.split("\n")
+		.filter((line) => line.length > 0)
+		.map((line) => JSON.parse(line) as Line);
+};
+
+describe("log level", () => {
+	it("reports an unusable LOG_LEVEL instead of failing or ignoring it", () => {
+		assert.equal(startup.length, 1);
+		const [line] = startup;
+		assert.equal(line.level, "warn");
+		assert.match(String(line.msg), /LOG_LEVEL/);
+		assert.equal(line.configured, "verbose");
+		assert.match(String(line.expected), /trace/);
+	});
+
+	it("falls back to info, so debug and trace are dropped", () => {
+		const log = createLogger();
+		const lines = capture(() => {
+			log.trace("dropped");
+			log.debug("dropped");
+			log.warn("kept");
+		});
+		assert.deepEqual(
+			lines.map((line) => line.msg),
+			["kept"],
+		);
+	});
+
+	it("defaults the service name when none is stamped into the build", () => {
+		const [line] = capture(() => createLogger().warn("unnamed"));
+		assert.equal(line.service, "remit");
+	});
+});

package/src/log-output.test.ts

@@ -0,0 +1,355 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+
+// The field contract these tests pin down is documented for operators in
+// deploy/vps/README.md ("Logs"). A change here is a change to what every
+// log-shipping rule against this deployment parses.
+process.env.LOG_LEVEL = "trace";
+process.env.REMIT_SERVICE_NAME = "test-service";
+
+type Line = Record<string, unknown>;
+
+const originalWrite = process.stdout.write.bind(process.stdout);
+const written: string[] = [];
+let capturing = false;
+
+// pino uses `process.stdout` directly when its `write` has been replaced, and
+// the real fd otherwise — so the hook has to be in place before the import
+// below, and it passes writes through whenever a test is not capturing so the
+// test runner's own output still reaches the terminal.
+process.stdout.write = ((
+	chunk: string | Uint8Array,
+	...rest: unknown[]
+): boolean => {
+	if (capturing && typeof chunk === "string") {
+		written.push(chunk);
+		return true;
+	}
+	return (originalWrite as (...args: unknown[]) => boolean)(chunk, ...rest);
+}) as typeof process.stdout.write;
+
+const { createLogger, logger, withLogContext } = await import("./logger.js");
+
+const parse = (): Line[] =>
+	written
+		.join("")
+		.split("\n")
+		.filter((line) => line.length > 0)
+		.map((line) => JSON.parse(line) as Line);
+
+const capture = (emit: () => void): Line[] => {
+	written.length = 0;
+	capturing = true;
+	try {
+		emit();
+	} finally {
+		capturing = false;
+	}
+	return parse();
+};
+
+const captureAsync = async (emit: () => Promise<void>): Promise<Line[]> => {
+	written.length = 0;
+	capturing = true;
+	try {
+		await emit();
+	} finally {
+		capturing = false;
+	}
+	return parse();
+};
+
+const one = (emit: () => void): Line => {
+	const lines = capture(emit);
+	assert.equal(lines.length, 1, "expected exactly one log line");
+	return lines[0];
+};
+
+describe("log output", () => {
+	it("writes one JSON object per line on stdout", () => {
+		const log = createLogger();
+		const lines = capture(() => {
+			log.warn("first");
+			log.warn("second");
+		});
+		assert.deepEqual(
+			lines.map((line) => line.msg),
+			["first", "second"],
+		);
+	});
+
+	it("carries level, time, service and msg on every line", () => {
+		const line = one(() => createLogger().warn("hello"));
+		assert.equal(line.level, "warn");
+		assert.equal(line.service, "test-service");
+		assert.equal(line.msg, "hello");
+		assert.equal(typeof line.time, "string");
+		assert.equal(
+			new Date(line.time as string).toISOString(),
+			line.time,
+			"time is RFC 3339 in UTC",
+		);
+	});
+
+	it("names each level in lowercase, with fatal as its own name", () => {
+		const log = createLogger();
+		const levels = capture(() => {
+			log.trace("t");
+			log.debug("d");
+			log.info("i");
+			log.warn("w");
+			log.error("e");
+			log.fatal("f");
+		}).map((line) => line.level);
+		assert.deepEqual(levels, [
+			"trace",
+			"debug",
+			"info",
+			"warn",
+			"error",
+			"fatal",
+		]);
+	});
+
+	it("puts bindings at the top level, message first", () => {
+		const line = one(() =>
+			createLogger().error(
+				{ error: "boom", messageId: "m1" },
+				"Failed to parse message",
+			),
+		);
+		assert.equal(line.msg, "Failed to parse message");
+		assert.equal(line.error, "boom");
+		assert.equal(line.messageId, "m1");
+	});
+
+	it("emits an empty msg when only bindings are given", () => {
+		const line = one(() => createLogger().warn({ count: 3 }));
+		assert.equal(line.msg, "");
+		assert.equal(line.count, 3);
+	});
+
+	it("accepts bindings after a message", () => {
+		const line = one(() =>
+			createLogger().warn("watch out", { reason: "slow" }),
+		);
+		assert.equal(line.msg, "watch out");
+		assert.equal(line.reason, "slow");
+	});
+
+	it("ignores a non-object second argument after a message", () => {
+		const line = one(() =>
+			(createLogger().warn as (msg: string, obj?: unknown) => void)(
+				"plain",
+				"not-bindings",
+			),
+		);
+		assert.equal(line.msg, "plain");
+	});
+
+	it("child bindings appear on every line the child writes", () => {
+		const child = createLogger().child({ queue: "imap" });
+		const line = one(() => child.warn({ done: true }, "child log"));
+		assert.equal(line.queue, "imap");
+		assert.equal(line.done, true);
+		assert.equal(line.msg, "child log");
+	});
+
+	it("a call-site field shadowing a child binding is written once", () => {
+		const child = createLogger().child({ queue: "from-child" });
+		const [line] = capture(() => child.warn({ queue: "from-callsite" }, "x"));
+		assert.equal(line.queue, "from-callsite");
+		const repeats = written.join("").match(/"queue"/g) ?? [];
+		assert.equal(repeats.length, 1, "one key per line, not two");
+	});
+
+	it("a child inherits the bindings its parent had when it was created", () => {
+		const parent = createLogger();
+		parent.setBindings({ accountId: "a1" });
+		const child = parent.child({ queue: "smtp" });
+		const line = one(() => child.warn("nested"));
+		assert.equal(line.accountId, "a1");
+		assert.equal(line.queue, "smtp");
+	});
+
+	it("setBindings applies to later lines and replaces a key without repeating it", () => {
+		const log = createLogger();
+		log.setBindings({ requestId: "r1", path: "/one" });
+		const first = one(() => log.warn("first request"));
+		assert.equal(first.requestId, "r1");
+		assert.equal(first.path, "/one");
+
+		log.setBindings({ requestId: "r2", path: "/two" });
+		const [raw] = capture(() => log.warn("second request"));
+		assert.equal(raw.requestId, "r2");
+		assert.equal(raw.path, "/two");
+
+		const repeats = written.join("").match(/"requestId"/g) ?? [];
+		assert.equal(repeats.length, 1, "a rebound key is written once, not twice");
+	});
+
+	it("bindings set on one logger do not leak into another", () => {
+		const first = createLogger();
+		const second = createLogger();
+		first.setBindings({ owner: "first" });
+		const line = one(() => second.warn("independent"));
+		assert.equal(line.owner, undefined);
+	});
+
+	it("the shared logger writes the same shape", () => {
+		const line = one(() => logger.warn("shared"));
+		assert.equal(line.service, "test-service");
+		assert.equal(line.msg, "shared");
+	});
+
+	it("carries no pid or hostname", () => {
+		const line = one(() => createLogger().warn("lean"));
+		assert.equal(line.pid, undefined);
+		assert.equal(line.hostname, undefined);
+	});
+
+	it("drops a call-site field using a reserved name", () => {
+		const [line] = capture(() =>
+			createLogger().warn(
+				{ level: "trace", time: "1999", service: "other", msg: "hijack" },
+				"collide",
+			),
+		);
+		assert.equal(line.level, "warn");
+		assert.equal(line.service, "test-service");
+		assert.equal(line.msg, "collide");
+		for (const key of ['"level"', '"time"', '"service"', '"msg"']) {
+			const repeats = written.join("").match(new RegExp(key, "g")) ?? [];
+			assert.equal(repeats.length, 1, `${key} is written once`);
+		}
+	});
+});
+
+// The shapes the worker and backend failure paths actually produce. A contract
+// test that asserts a key no call site writes is how a serialisation regression
+// stays green, so each case below names the call site it mirrors.
+describe("error serialisation", () => {
+	it("expands an Error logged under error — imap-worker/src/index.ts", () => {
+		const line = one(() =>
+			createLogger().error(
+				{ error: new Error("boom"), messageId: "m1" },
+				"Event processing failed",
+			),
+		);
+		const error = line.error as Record<string, unknown>;
+		assert.equal(error.type, "Error");
+		assert.equal(error.message, "boom");
+		assert.match(String(error.stack), /^Error: boom\n\s+at /);
+		assert.equal(line.messageId, "m1");
+	});
+
+	it("keeps a subclass name and its own properties", () => {
+		class UpstreamError extends Error {
+			readonly statusCode = 502;
+		}
+		const line = one(() =>
+			createLogger().error({ error: new UpstreamError("gone") }, "failed"),
+		);
+		const error = line.error as Record<string, unknown>;
+		assert.equal(error.type, "UpstreamError");
+		assert.equal(error.statusCode, 502);
+	});
+
+	it("leaves a string alone — backend/src/error.ts", () => {
+		const failure = new Error("ElectroError: bad key");
+		const line = one(() =>
+			createLogger().error(
+				{ error: failure.message, name: failure.name, stack: failure.stack },
+				"Unhandled Error",
+			),
+		);
+		assert.equal(line.error, "ElectroError: bad key");
+		assert.equal(line.name, "Error");
+		assert.match(String(line.stack), /^Error: ElectroError: bad key\n\s+at /);
+	});
+
+	it("leaves a plain object alone — backend/src/response.ts", () => {
+		const line = one(() =>
+			createLogger().error(
+				{ "problematicValue_/items": { path: "/items", error: "too long" } },
+				"Response validation failed",
+			),
+		);
+		assert.deepEqual(line["problematicValue_/items"], {
+			path: "/items",
+			error: "too long",
+		});
+	});
+
+	it("expands an Error under err too", () => {
+		const line = one(() =>
+			createLogger().error({ err: new Error("kaboom") }, "handler failed"),
+		);
+		const err = line.err as Record<string, unknown>;
+		assert.equal(err.type, "Error");
+		assert.equal(err.message, "kaboom");
+	});
+});
+
+describe("withLogContext", () => {
+	it("adds its bindings to every line written inside it", () => {
+		const line = one(() =>
+			withLogContext({ requestId: "r1", path: "/one" }, () => {
+				logger.warn("inside");
+			}),
+		);
+		assert.equal(line.requestId, "r1");
+		assert.equal(line.path, "/one");
+	});
+
+	it("does not leak past the scope", () => {
+		withLogContext({ requestId: "r1" }, () => {});
+		const line = one(() => logger.warn("outside"));
+		assert.equal(line.requestId, undefined);
+	});
+
+	it("keeps overlapping scopes apart across awaits", async () => {
+		const request = (id: string, delayMs: number) =>
+			withLogContext({ requestId: id }, async () => {
+				await new Promise((resolve) => setTimeout(resolve, delayMs));
+				logger.warn(`handled ${id}`);
+			});
+
+		// The slow request opens its scope first and logs last, which is exactly
+		// the interleaving a shared mutable binding gets wrong.
+		const lines = await captureAsync(async () => {
+			await Promise.all([request("slow", 10), request("fast", 1)]);
+		});
+
+		assert.deepEqual(
+			lines.map((line) => [line.msg, line.requestId]),
+			[
+				["handled fast", "fast"],
+				["handled slow", "slow"],
+			],
+		);
+	});
+
+	it("nests, adding to the scope it runs inside", () => {
+		const line = one(() =>
+			withLogContext({ requestId: "r1" }, () =>
+				withLogContext({ accountId: "a1" }, () => {
+					logger.warn("nested scope");
+				}),
+			),
+		);
+		assert.equal(line.requestId, "r1");
+		assert.equal(line.accountId, "a1");
+	});
+
+	it("a call-site field wins over a scope binding, and is written once", () => {
+		const [line] = capture(() =>
+			withLogContext({ requestId: "from-scope" }, () => {
+				logger.warn({ requestId: "from-callsite" }, "x");
+			}),
+		);
+		assert.equal(line.requestId, "from-callsite");
+		const repeats = written.join("").match(/"requestId"/g) ?? [];
+		assert.equal(repeats.length, 1);
+	});
+});

package/src/logger.test.ts

@@ -2,31 +2,14 @@ import assert from "node:assert/strict";
 import { beforeEach, describe, it, mock } from "node:test";
 import type { Context } from "aws-lambda";
 
+// The logging half of this package is covered by log-output.test.ts against its
+// real stdout output; this file is the telemetry wrapper, so the logger is
+// silenced and only the metric calls are observed.
+process.env.LOG_LEVEL = "silent";
+
 const addMetric = mock.fn();
 const publishStoredMetrics = mock.fn();
 const captureColdStartMetric = mock.fn();
-const addContext = mock.fn();
-const logTrace = mock.fn();
-const logDebug = mock.fn();
-const logInfo = mock.fn();
-const logWarn = mock.fn();
-const logError = mock.fn();
-const logCritical = mock.fn();
-const appendPersistentKeys = mock.fn();
-
-class MockLogger {
-	addContext = addContext;
-	trace = logTrace;
-	debug = logDebug;
-	info = logInfo;
-	warn = logWarn;
-	error = logError;
-	critical = logCritical;
-	appendPersistentKeys = appendPersistentKeys;
-	createChild = () => createChild();
-}
-
-const createChild = mock.fn(() => new MockLogger());
 
 class MockMetrics {
 	addMetric = addMetric;
@@ -34,10 +17,6 @@ class MockMetrics {
 	captureColdStartMetric = captureColdStartMetric;
 }
 
-mock.module("@aws-lambda-powertools/logger", {
-	namedExports: { Logger: MockLogger },
-});
-
 mock.module("@aws-lambda-powertools/metrics", {
 	namedExports: {
 		Metrics: MockMetrics,
@@ -45,7 +24,7 @@ mock.module("@aws-lambda-powertools/metrics", {
 	},
 });
 
-const { createLogger, metrics, withTelemetry } = await import("./logger.js");
+const { metrics, withTelemetry } = await import("./logger.js");
 const { Metrics } = await import("@aws-lambda-powertools/metrics");
 
 type Recorded = { mock: { calls: { arguments: unknown[] }[] } };
@@ -53,26 +32,7 @@ type Recorded = { mock: { calls: { arguments: unknown[] }[] } };
 const calls = (fn: Recorded): unknown[][] =>
 	fn.mock.calls.map((call) => call.arguments);
 
-const lastCall = (fn: Recorded): unknown[] => {
-	const recorded = calls(fn);
-	assert.ok(recorded.length > 0, "expected the mock to have been called");
-	return recorded[recorded.length - 1];
-};
-
-const recorded = [
-	addMetric,
-	publishStoredMetrics,
-	captureColdStartMetric,
-	addContext,
-	logTrace,
-	logDebug,
-	logInfo,
-	logWarn,
-	logError,
-	logCritical,
-	appendPersistentKeys,
-	createChild,
-];
+const recorded = [addMetric, publishStoredMetrics, captureColdStartMetric];
 
 const makeContext = (): Context =>
 	({
@@ -99,60 +59,6 @@ describe("remit-logger-lambda", () => {
 		assert.ok(metrics instanceof Metrics);
 	});
 
-	it("object-first call maps to Powertools message + attributes", () => {
-		const log = createLogger(makeContext());
-		log.error({ error: "boom", messageId: "m1" }, "Failed to parse message");
-		assert.deepEqual(lastCall(logError), [
-			"Failed to parse message",
-			{ error: "boom", messageId: "m1" },
-		]);
-	});
-
-	it("object-first call without message uses empty string", () => {
-		const log = createLogger();
-		log.info({ count: 3 });
-		assert.deepEqual(lastCall(logInfo), ["", { count: 3 }]);
-	});
-
-	it("string-first call passes message then attributes", () => {
-		const log = createLogger();
-		log.warn("watch out", { reason: "slow" });
-		assert.deepEqual(lastCall(logWarn), ["watch out", { reason: "slow" }]);
-	});
-
-	it("string-first call without attributes passes only the message", () => {
-		const log = createLogger();
-		log.debug("hello");
-		assert.deepEqual(lastCall(logDebug), ["hello"]);
-	});
-
-	it("fatal maps to Powertools critical", () => {
-		const log = createLogger();
-		log.fatal({ fatal: true }, "the end");
-		assert.deepEqual(lastCall(logCritical), ["the end", { fatal: true }]);
-	});
-
-	it("trace maps to Powertools trace", () => {
-		const log = createLogger();
-		log.trace("trace me");
-		assert.deepEqual(lastCall(logTrace), ["trace me"]);
-	});
-
-	it("child creates a Powertools child and appends bindings", () => {
-		const log = createLogger();
-		const child = log.child({ queue: "imap" });
-		assert.equal(calls(createChild).length, 1);
-		assert.deepEqual(lastCall(appendPersistentKeys), [{ queue: "imap" }]);
-		child.info({ done: true }, "child log");
-		assert.deepEqual(lastCall(logInfo), ["child log", { done: true }]);
-	});
-
-	it("setBindings appends persistent keys", () => {
-		const log = createLogger();
-		log.setBindings({ requestId: "r1" });
-		assert.deepEqual(lastCall(appendPersistentKeys), [{ requestId: "r1" }]);
-	});
-
 	it("withTelemetry calls the handler and returns its result", async () => {
 		const handler = mock.fn(async () => "hello");
 		const wrapped = withTelemetry(handler);

package/src/logger.ts

@@ -1,40 +1,90 @@
-import { Logger as PowertoolsLogger } from "@aws-lambda-powertools/logger";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { Metrics, MetricUnit } from "@aws-lambda-powertools/metrics";
 import type { Context } from "aws-lambda";
+import { pino, stdSerializers } from "pino";
 
 type LogBindings = Record<string, unknown>;
 
-type PowertoolsLevel =
-	| "trace"
-	| "debug"
-	| "info"
-	| "warn"
-	| "error"
-	| "critical";
+type EmitLevel = "trace" | "debug" | "info" | "warn" | "error" | "fatal";
+
+const LEVELS = [
+	"trace",
+	"debug",
+	"info",
+	"warn",
+	"error",
+	"fatal",
+	"silent",
+] as const;
+
+const DEFAULT_LEVEL = "info";
+
+const isLevel = (value: string): boolean =>
+	(LEVELS as readonly string[]).includes(value);
+
+const requestedLevel = process.env.LOG_LEVEL?.trim().toLowerCase();
+
+const level =
+	requestedLevel && isLevel(requestedLevel) ? requestedLevel : DEFAULT_LEVEL;
 
 const isBindings = (value: unknown): value is LogBindings =>
 	typeof value === "object" && value !== null;
 
-const emit = (
-	target: PowertoolsLogger,
-	level: PowertoolsLevel,
+// Written by the writer itself, so a binding of the same name would be a second
+// occurrence of the key on the line and every JSON parser takes the last one —
+// a call-site field named `level` would silently retag the line. Dropped rather
+// than renamed: a field the operator cannot rely on is worse than an absent one.
+const RESERVED = ["level", "time", "service", "msg"] as const;
+
+const withoutReserved = (fields: LogBindings): LogBindings => {
+	let kept: LogBindings | undefined;
+	for (const key of RESERVED) {
+		if (!(key in fields)) continue;
+		kept ??= { ...fields };
+		delete kept[key];
+	}
+	return kept ?? fields;
+};
+
+// One JSON object per line on stdout: `level` as a lowercase name, `time` as
+// RFC 3339, `service` naming the image, `msg` always present, and every binding
+// at the top level. The field contract is documented in deploy/vps/README.md
+// under "Logs" — log-shipping rules are written against these names.
+//
+// `error` carries an Error at most call sites in this repo, so it is serialised
+// the way pino serialises `err`: a bare Error spreads to nothing, which is how a
+// stack trace disappears from a worker failure line.
+const root = pino({
+	level,
+	base: { service: process.env.REMIT_SERVICE_NAME ?? "remit" },
+	timestamp: pino.stdTimeFunctions.isoTime,
+	formatters: { level: (label: string) => ({ level: label }) },
+	serializers: { error: stdSerializers.err },
+});
+
+type PinoLogger = typeof root;
+
+// A level nobody can spell is worth one line rather than a crashed container:
+// the operator asked for something and did not get it, and every other line
+// still arrives.
+if (requestedLevel && requestedLevel !== level) {
+	root.warn(
+		{ configured: requestedLevel, expected: LEVELS.join(", ") },
+		`LOG_LEVEL is not a level name; logging at ${level}`,
+	);
+}
+
+// The interface accepts (bindings, message) and (message, bindings); pino reads
+// (bindings, message) only, and treats an object after a string message as a
+// format argument. Normalising here is what keeps both call shapes working.
+const normalize = (
 	first: LogBindings | string,
 	second?: LogBindings | string,
-): void => {
-	if (typeof first !== "string") {
-		const message = typeof second === "string" ? second : "";
-		target[level](message, first);
-		return;
-	}
-	if (second === undefined) {
-		target[level](first);
-		return;
+): [LogBindings, string] => {
+	if (typeof first === "string") {
+		return [isBindings(second) ? second : {}, first];
 	}
-	if (typeof second === "string") {
-		target[level](first, second);
-		return;
-	}
-	target[level](first, second);
+	return [first, typeof second === "string" ? second : ""];
 };
 
 export interface Logger {
@@ -54,50 +104,70 @@ export interface Logger {
 	setBindings(bindings: LogBindings): void;
 }
 
-const createAdapter = (target: PowertoolsLogger): Logger => ({
-	trace: (first: LogBindings | string, second?: LogBindings | string): void =>
-		emit(target, "trace", first, second),
-	debug: (first: LogBindings | string, second?: LogBindings | string): void =>
-		emit(target, "debug", first, second),
-	info: (first: LogBindings | string, second?: LogBindings | string): void =>
-		emit(target, "info", first, second),
-	warn: (first: LogBindings | string, second?: LogBindings | string): void =>
-		emit(target, "warn", first, second),
-	error: (first: LogBindings | string, second?: LogBindings | string): void =>
-		emit(target, "error", first, second),
-	fatal: (first: LogBindings | string, second?: LogBindings | string): void =>
-		emit(target, "critical", first, second),
-	child: (bindings: LogBindings): Logger => {
-		const childLogger = target.createChild();
-		if (isBindings(bindings)) {
-			childLogger.appendPersistentKeys(bindings);
-		}
-		return createAdapter(childLogger);
-	},
-	setBindings: (bindings: LogBindings): void => {
-		target.appendPersistentKeys(bindings);
-	},
-});
+// Bindings from a scope opened by withLogContext. A server handling requests
+// concurrently cannot carry per-request fields on a shared logger instance:
+// whichever request wrote last owns them until the next one overwrites them.
+const scope = new AsyncLocalStorage<LogBindings>();
+
+/**
+ * Runs `fn` with `bindings` on every line any logger writes inside it,
+ * including asynchronous continuations. Scopes nest: an inner call adds to the
+ * bindings of the one it runs inside.
+ */
+export const withLogContext = <T>(bindings: LogBindings, fn: () => T): T =>
+	scope.run({ ...scope.getStore(), ...bindings }, fn);
+
+// Every binding is merged into one object here rather than handed to pino:
+// pino's own child/setBindings append to a cached string it writes verbatim, so
+// a shadowing key would appear twice on one line, and a per-request setBindings
+// on a long-lived logger would grow that string without bound.
+const createAdapter = (target: PinoLogger, persistent: LogBindings): Logger => {
+	const emit = (
+		level: EmitLevel,
+		first: LogBindings | string,
+		second?: LogBindings | string,
+	): void => {
+		const [fields, message] = normalize(first, second);
+		target[level](
+			withoutReserved({ ...persistent, ...scope.getStore(), ...fields }),
+			message,
+		);
+	};
 
-const powertoolsLogger = new PowertoolsLogger({
-	serviceName: process.env.POWERTOOLS_SERVICE_NAME ?? "remit",
-});
+	return {
+		trace: (first: LogBindings | string, second?: LogBindings | string): void =>
+			emit("trace", first, second),
+		debug: (first: LogBindings | string, second?: LogBindings | string): void =>
+			emit("debug", first, second),
+		info: (first: LogBindings | string, second?: LogBindings | string): void =>
+			emit("info", first, second),
+		warn: (first: LogBindings | string, second?: LogBindings | string): void =>
+			emit("warn", first, second),
+		error: (first: LogBindings | string, second?: LogBindings | string): void =>
+			emit("error", first, second),
+		fatal: (first: LogBindings | string, second?: LogBindings | string): void =>
+			emit("fatal", first, second),
+		child: (bindings: LogBindings): Logger =>
+			createAdapter(target, { ...persistent, ...bindings }),
+		setBindings: (bindings: LogBindings): void => {
+			Object.assign(persistent, bindings);
+		},
+	};
+};
 
-export const logger: Logger = createAdapter(powertoolsLogger);
+export const logger: Logger = createAdapter(root, {});
 
 export const metrics = new Metrics({
 	namespace: process.env.POWERTOOLS_METRICS_NAMESPACE ?? "Remit",
 	serviceName: process.env.POWERTOOLS_SERVICE_NAME ?? "remit",
 });
 
-export const createLogger = (_context?: Context): Logger =>
-	createAdapter(powertoolsLogger);
+export const createLogger = (): Logger => createAdapter(root, {});
 
 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> => {
-		powertoolsLogger.addContext(context);
 		logger.debug("Lambda invocation started", {
 			functionName: context.functionName,
 		});
@@ -116,7 +186,7 @@ export const withTelemetry = <TEvent, TResult>(
 			return result;
 		} catch (err) {
 			metrics.addMetric("errorCount", MetricUnit.Count, 1);
-			logger.error("Lambda invocation failed", { error: String(err) });
+			logger.error("Lambda invocation failed", { error: err });
 			throw err;
 		} finally {
 			metrics.publishStoredMetrics();