Add allocation metrics

Author: stevebux

lambdas/supplier-allocator/package.json

@@ -9,6 +9,7 @@
     "@nhsdigital/nhs-notify-event-schemas-letter-rendering-v1": "npm:@nhsdigital/nhs-notify-event-schemas-letter-rendering@^1.1.5",
     "@nhsdigital/nhs-notify-event-schemas-supplier-api": "^1.0.8",
     "@types/aws-lambda": "^8.10.148",
+    "aws-embedded-metrics": "^4.2.1",
     "aws-lambda": "^1.0.7",
     "esbuild": "^0.27.2",
     "pino": "^9.7.0",

lambdas/supplier-allocator/src/handler/__tests__/allocate-handler.test.ts

@@ -7,10 +7,39 @@ import {
   $LetterEvent,
   LetterEvent,
 } from "@nhsdigital/nhs-notify-event-schemas-supplier-api/src/events/letter-events";
+import { MetricStatus } from "@internal/helpers";
 import createSupplierAllocatorHandler from "../allocate-handler";
 import { Deps } from "../../config/deps";
 import { EnvVars } from "../../config/env";
 
+function assertMetricLogged(
+  logger: pino.Logger,
+  supplier: string,
+  priority: string,
+  status: MetricStatus,
+  count: number,
+) {
+  expect(logger.info).toHaveBeenCalledWith(
+    expect.objectContaining({
+      Supplier: supplier,
+      Priority: priority,
+      _aws: expect.objectContaining({
+        CloudWatchMetrics: expect.arrayContaining([
+          expect.objectContaining({
+            Metrics: [
+              expect.objectContaining({
+                Name: status,
+                Value: count,
+              }),
+            ],
+          }),
+        ]),
+      }),
+      [status]: count,
+    }),
+  );
+}
+
 function createSQSEvent(records: SQSRecord[]): SQSEvent {
   return {
     Records: records,
@@ -182,6 +211,14 @@ describe("createSupplierAllocatorHandler", () => {
       specId: "spec1",
       priority: 10,
     });
+
+    assertMetricLogged(
+      mockedDeps.logger,
+      "supplier1",
+      "10",
+      MetricStatus.Success,
+      1,
+    );
   });
 
   test("parses SNS notification and sends message to SQS queue for v1 event", async () => {
@@ -229,6 +266,14 @@ describe("createSupplierAllocatorHandler", () => {
     expect(result.batchItemFailures).toHaveLength(1);
     expect(result.batchItemFailures[0].itemIdentifier).toBe("invalid-event");
     expect((mockedDeps.logger.error as jest.Mock).mock.calls).toHaveLength(1);
+
+    assertMetricLogged(
+      mockedDeps.logger,
+      "unknown",
+      "unknown",
+      MetricStatus.Failure,
+      1,
+    );
   });
 
   test("unwraps EventBridge envelope and extracts event details", async () => {
@@ -398,6 +443,14 @@ describe("createSupplierAllocatorHandler", () => {
     expect(result.batchItemFailures).toHaveLength(1);
     expect(result.batchItemFailures[0].itemIdentifier).toBe("msg1");
     expect((mockedDeps.logger.error as jest.Mock).mock.calls).toHaveLength(1);
+
+    assertMetricLogged(
+      mockedDeps.logger,
+      "supplier1",
+      "10",
+      MetricStatus.Failure,
+      1,
+    );
   });
 
   test("processes mixed batch with successes and failures", async () => {
@@ -423,6 +476,21 @@ describe("createSupplierAllocatorHandler", () => {
     expect(result.batchItemFailures[0].itemIdentifier).toBe("fail-msg");
 
     expect(mockSqsClient.send).toHaveBeenCalledTimes(2);
+
+    assertMetricLogged(
+      mockedDeps.logger,
+      "supplier1",
+      "10",
+      MetricStatus.Success,
+      2,
+    );
+    assertMetricLogged(
+      mockedDeps.logger,
+      "unknown",
+      "unknown",
+      MetricStatus.Failure,
+      1,
+    );
   });
 
   test("sends correct queue URL in SQS message command", async () => {
@@ -441,4 +509,48 @@ describe("createSupplierAllocatorHandler", () => {
     const sendCall = (mockSqsClient.send as jest.Mock).mock.calls[0][0];
     expect(sendCall.input.QueueUrl).toBe(queueUrl);
   });
+
+  test("emits separate metrics per supplier and priority combination", async () => {
+    mockedDeps.env.VARIANT_MAP = {
+      lv1: { supplierId: "supplier1", specId: "spec1", priority: 10 },
+      lv2: { supplierId: "supplier2", specId: "spec2", priority: 5 },
+    } as any;
+
+    const eventForSupplier1 = createPreparedV2Event({ domainId: "letter1" });
+    const eventForSupplier2 = {
+      ...createPreparedV2Event({ domainId: "letter2" }),
+      data: {
+        ...createPreparedV2Event({ domainId: "letter2" }).data,
+        letterVariantId: "lv2",
+      },
+    };
+
+    const evt: SQSEvent = createSQSEvent([
+      createSqsRecord("msg1", JSON.stringify(eventForSupplier1)),
+      createSqsRecord("msg2", JSON.stringify(eventForSupplier2)),
+    ]);
+
+    process.env.UPSERT_LETTERS_QUEUE_URL = "https://sqs.test.queue";
+
+    const handler = createSupplierAllocatorHandler(mockedDeps);
+    const result = await handler(evt, {} as any, {} as any);
+    if (!result) throw new Error("expected BatchResponse, got void");
+
+    expect(result.batchItemFailures).toHaveLength(0);
+
+    assertMetricLogged(
+      mockedDeps.logger,
+      "supplier1",
+      "10",
+      MetricStatus.Success,
+      1,
+    );
+    assertMetricLogged(
+      mockedDeps.logger,
+      "supplier2",
+      "5",
+      MetricStatus.Success,
+      1,
+    );
+  });
 });

lambdas/supplier-allocator/src/handler/allocate-handler.ts

@@ -4,9 +4,11 @@ import { LetterRequestPreparedEvent } from "@nhsdigital/nhs-notify-event-schemas
 
 import { LetterRequestPreparedEventV2 } from "@nhsdigital/nhs-notify-event-schemas-letter-rendering";
 import z from "zod";
+import { Unit } from "aws-embedded-metrics";
+import { MetricEntry, MetricStatus, buildEMFObject } from "@internal/helpers";
 import { Deps } from "../config/deps";
 
-type SupplierSpec = { supplierId: string; specId: string };
+type SupplierSpec = { supplierId: string; specId: string; priority: number };
 type PreparedEvents = LetterRequestPreparedEventV2 | LetterRequestPreparedEvent;
 
 // small envelope that must exist in all inputs
@@ -50,11 +52,63 @@ function getSupplier(letterEvent: PreparedEvents, deps: Deps): SupplierSpec {
   return resolveSupplierForVariant(letterEvent.data.letterVariantId, deps);
 }
 
+type AllocationMetrics = Map<string, Map<string, number>>;
+
+function incrementMetric(
+  map: AllocationMetrics,
+  supplier: string,
+  priority: string,
+) {
+  const byPriority = map.get(supplier) ?? new Map<string, number>();
+  byPriority.set(priority, (byPriority.get(priority) ?? 0) + 1);
+  map.set(supplier, byPriority);
+}
+
+function emitMetrics(
+  successMetrics: AllocationMetrics,
+  failedMetrics: AllocationMetrics,
+  deps: Deps,
+) {
+  const namespace = "supplier-allocator";
+  for (const [supplier, byPriority] of successMetrics) {
+    for (const [priority, count] of byPriority) {
+      const dimensions: Record<string, string> = {
+        Priority: priority,
+        Supplier: supplier,
+      };
+      const metric: MetricEntry = {
+        key: MetricStatus.Success,
+        value: count,
+        unit: Unit.Count,
+      };
+      deps.logger.info(buildEMFObject(namespace, dimensions, metric));
+    }
+  }
+  for (const [supplier, byPriority] of failedMetrics) {
+    for (const [priority, count] of byPriority) {
+      const dimensions: Record<string, string> = {
+        Priority: priority,
+        Supplier: supplier,
+      };
+      const metric: MetricEntry = {
+        key: MetricStatus.Failure,
+        value: count,
+        unit: Unit.Count,
+      };
+      deps.logger.info(buildEMFObject(namespace, dimensions, metric));
+    }
+  }
+}
+
 export default function createSupplierAllocatorHandler(deps: Deps): SQSHandler {
   return async (event: SQSEvent) => {
     const batchItemFailures: SQSBatchItemFailure[] = [];
+    const perAllocationSuccess: AllocationMetrics = new Map();
+    const perAllocationFailure: AllocationMetrics = new Map();
 
     const tasks = event.Records.map(async (record) => {
+      let supplier = "unknown";
+      let priority = "unknown";
       try {
         const letterEvent: unknown = JSON.parse(record.body);
 
@@ -67,6 +121,9 @@ export default function createSupplierAllocatorHandler(deps: Deps): SQSHandler {
 
         const supplierSpec = getSupplier(letterEvent as PreparedEvents, deps);
 
+        supplier = supplierSpec.supplierId;
+        priority = String(supplierSpec.priority);
+
         deps.logger.info({
           description: "Resolved supplier spec",
           supplierSpec,
@@ -95,19 +152,23 @@ export default function createSupplierAllocatorHandler(deps: Deps): SQSHandler {
             MessageBody: JSON.stringify(queueMessage),
           }),
         );
+
+        incrementMetric(perAllocationSuccess, supplier, priority);
       } catch (error) {
         deps.logger.error({
           description: "Error processing allocation of record",
           err: error,
           messageId: record.messageId,
           message: record.body,
         });
+        incrementMetric(perAllocationFailure, supplier, priority);
         batchItemFailures.push({ itemIdentifier: record.messageId });
       }
     });
 
     await Promise.all(tasks);
 
+    emitMetrics(perAllocationSuccess, perAllocationFailure, deps);
     return { batchItemFailures };
   };
 }