From 5de94d389a14892c0a83a7319c4520035374aa70 Mon Sep 17 00:00:00 2001
From: Justin Rowles <justin.rowles.contractor@guardian.co.uk>
Date: Thu, 27 Aug 2026 16:31:35 +0100
Subject: [PATCH 1/2] Handle sigterm better in instrumentation

---
 .../src/server/instrumentation.ts             | 32 +++++++++++++++----
 1 file changed, 26 insertions(+), 6 deletions(-)

diff --git a/dotcom-rendering/src/server/instrumentation.ts b/dotcom-rendering/src/server/instrumentation.ts
index 2d4d5e2820a..2e27a4a3113 100644
--- a/dotcom-rendering/src/server/instrumentation.ts
+++ b/dotcom-rendering/src/server/instrumentation.ts
@@ -44,11 +44,31 @@ const sdk = new NodeSDK({
 
 sdk.start();
 
+// Instrumentation is preloaded into the same process as the app server.
+// It should react to process SIGTERM, but not own process/server lifecycle.
+let shutdownPromise: Promise<void> | null = null;
+
+const shutdownInstrumentation = (): Promise<void> => {
+	if (shutdownPromise !== null) {
+		logger.error(
+			'SIGTERM received; Instrumentation SDK is already shutting down',
+		);
+		return shutdownPromise;
+	}
+
+	logger.info('SIGTERM received; Instrumentation SDK shutting down');
+	shutdownPromise = sdk.shutdown().then(
+		() => {
+			logger.info('Instrumentation SDK shut down successfully');
+		},
+		(err) => {
+			logger.error('Error shutting down Instrumentation SDK', err);
+		},
+	);
+
+	return shutdownPromise;
+};
+
 process.on('SIGTERM', () => {
-	sdk.shutdown()
-		.then(
-			() => logger.info('SDK shut down successfully'),
-			(err) => logger.error('Error shutting down SDK', err),
-		)
-		.finally(() => process.exit(0));
+	void shutdownInstrumentation();
 });

From d21039bc552d4cb2451978125e3de1390c48e535 Mon Sep 17 00:00:00 2001
From: Justin Rowles <justin.rowles.contractor@guardian.co.uk>
Date: Fri, 28 Aug 2026 12:52:44 +0100
Subject: [PATCH 2/2] Add basic documentation

---
 dotcom-rendering/docs/img.png   | Bin 0 -> 13426 bytes
 dotcom-rendering/docs/traces.md | 167 ++++++++++++++++++++++++++++++++
 2 files changed, 167 insertions(+)
 create mode 100644 dotcom-rendering/docs/img.png
 create mode 100644 dotcom-rendering/docs/traces.md

diff --git a/dotcom-rendering/docs/img.png b/dotcom-rendering/docs/img.png
new file mode 100644
index 0000000000000000000000000000000000000000..ef74f1e89a2fbacccdec8e79b1c084d7f73fc490
GIT binary patch
literal 13426
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

literal 0
HcmV?d00001

diff --git a/dotcom-rendering/docs/traces.md b/dotcom-rendering/docs/traces.md
new file mode 100644
index 00000000000..dc823f0771a
--- /dev/null
+++ b/dotcom-rendering/docs/traces.md
@@ -0,0 +1,167 @@
+# Traces
+
+AWS Cloudwatch Traces are added by `createRequestTracingMiddleware`. They can be viewed in the aws Cloudwatch console
+
+If fetched using `aws xray batch-get-traces`, the trace document will contain a `Segment` field, which contains a
+`Document` field. The `Document` field is a JSON string containing the trace data we want.
+
+An example CLI request to view a single trace document as json is:
+
+# Set date range
+
+```
+start="$(date -u -d '5 hours ago' +%s)"
+end="$(date -u +%s)"
+```
+
+# List all services (currently only "tag-page-rendering")
+
+```
+aws xray get-service-graph \
+  --start-time "$start" \
+  --end-time "$end" \
+  --query 'Services[].Name'
+```
+
+# List all traces for a specific service, time range, and path
+
+```
+aws xray get-trace-summaries \
+  --start-time "$start" \
+  --end-time "$end" \
+  --filter-expression 'service("tag-page-rendering") AND http.url CONTAINS "/Article"' \
+  --query 'TraceSummaries[].Id'
+```
+
+# Get full info from a single trace
+
+```
+aws xray batch-get-traces \
+   --trace-ids 1-e805ee5f-1df00290c3be6a6cee361060 \
+   | jq -r '.Traces[0].Segments[0].Document' \
+   | jq '.'
+```
+
+It can be useful to add `metadata` to the trace document for use in the AWS UI.
+
+For example, we add `subsegments[0].metadata.http.route` to the trace document so it is visible onscreen:
+
+![img.png](img.png)
+
+An example of a complete segment document is below. We are likely to be interested in the following sections:
+
+- start_time (convert on a mac with `date -r <s>`)
+- end_time
+- metadata.default.http.request_content_length_uncompressed
+- http.request.url and http.request.method
+
+```
+{
+  "id": "7a193b1ebdceda4b",
+  "name": "tag-page-rendering",
+  "start_time": 1787914805.575,
+  "trace_id": "1-e805ee5f-1df00290c3be6a6cee361060",
+  "end_time": 1787914805.5822752,
+  "fault": false,
+  "error": false,
+  "throttle": false,
+  "http": {
+    "request": {
+      "url": "http://tag-page-rendering-jr.local.dev-gutools.co.uk/Article",
+      "method": "POST",
+      "user_agent": "curl/8.7.1",
+      "client_ip": "10.0.20.50"
+    },
+    "response": {
+      "status": 200,
+      "content_length": 0
+    }
+  },
+  "aws": {
+    "xray": {
+      "auto_instrumentation": false,
+      "sdk_version": "2.8.0",
+      "sdk": "opentelemetry for nodejs"
+    }
+  },
+  "metadata": {
+    "default": {
+      "otel.resource.process.command": "/app/server.js",
+      "otel.resource.telemetry.sdk.name": "opentelemetry",
+      "http.request_content_length_uncompressed": 3466,
+      "net.transport": "ip_tcp",
+      "http.flavor": "1.1",
+      "otel.resource.process.command_args": [
+        "/usr/bin/node",
+        "--require",
+        "/app/instrumentation.js",
+        "/app/server.js"
+      ],
+      "otel.resource.process.runtime.description": "Node.js",
+      "otel.resource.host.arch": "arm64",
+      "otel.resource.host.name": "ip-10-0-14-80.eu-west-1.compute.internal",
+      "otel.resource.process.runtime.version": "24.20.0",
+      "otel.resource.service.name": "tag-page-rendering",
+      "net.host.ip": "::ffff:10.0.14.80",
+      "otel.resource.process.executable.path": "/usr/bin/node",
+      "otel.resource.telemetry.sdk.version": "2.8.0",
+      "otel.resource.process.executable.name": "node",
+      "otel.resource.process.owner": "node",
+      "otel.resource.process.pid": 1,
+      "http.status_text": "OK",
+      "otel.resource.process.runtime.name": "nodejs",
+      "otel.resource.telemetry.sdk.language": "nodejs"
+    }
+  },
+  "subsegments": [
+    {
+      "id": "f6779849ceecde52",
+      "name": "request handler",
+      "start_time": 1787914805.576,
+      "end_time": 1787914805.582691,
+      "fault": false,
+      "error": false,
+      "throttle": false,
+      "http": {
+        "request": {
+          "method": "POST"
+        },
+        "response": {
+          "status": 200,
+          "content_length": 0
+        }
+      },
+      "aws": {
+        "xray": {
+          "auto_instrumentation": false,
+          "sdk_version": "2.8.0",
+          "sdk": "opentelemetry for nodejs"
+        }
+      },
+      "metadata": {
+        "default": {
+          "http.lifecycle.event": "finish",
+          "http.route": "/Article",
+          "http.aborted": false
+        }
+      }
+    },
+    {
+      "id": "c36bf9dd11b68a79",
+      "name": "express.json",
+      "start_time": 1787914805.575,
+      "end_time": 1787914805.57525,
+      "fault": false,
+      "error": false,
+      "throttle": false,
+      "aws": {
+        "xray": {
+          "auto_instrumentation": false,
+          "sdk_version": "2.8.0",
+          "sdk": "opentelemetry for nodejs"
+        }
+      }
+    }
+  ]
+}
+```