CCM-17942: Add Log Reference

infrastructure/terraform/components/api/module_authorizer_lambda.tf

@@ -39,6 +39,7 @@ module "authorizer_lambda" {
     CLIENT_CERTIFICATE_EXPIRATION_ALERT_DAYS = 30,
     APIM_SUPPLIER_ID_HEADER                  = "NHSD-Supplier-ID",
     SUPPLIERS_TABLE_NAME                     = aws_dynamodb_table.suppliers.name
+    LOG_REFERENCE                            = "AUTH"
   }
 }
 

infrastructure/terraform/components/api/module_lambda_amendment_event_transformer.tf

@@ -34,7 +34,9 @@ module "amendment_event_transformer" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "AMD_EVT_TRM"
+  })
 }
 
 data "aws_iam_policy_document" "amendment_event_transformer" {

infrastructure/terraform/components/api/module_lambda_get_letter.tf

@@ -34,7 +34,9 @@ module "get_letter" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "GET_LTR"
+  })
 }
 
 data "aws_iam_policy_document" "get_letter_lambda" {

infrastructure/terraform/components/api/module_lambda_get_letter_data.tf

@@ -34,7 +34,9 @@ module "get_letter_data" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "GET_LTR_DATA"
+  })
 }
 
 data "aws_iam_policy_document" "get_letter_data_lambda" {

infrastructure/terraform/components/api/module_lambda_get_letters.tf

@@ -35,7 +35,8 @@ module "get_letters" {
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
   lambda_env_vars = merge(local.common_lambda_env_vars, {
-    MAX_LIMIT = var.max_get_limit
+    MAX_LIMIT     = var.max_get_limit
+    LOG_REFERENCE = "GET_LTRS"
   })
 }
 

infrastructure/terraform/components/api/module_lambda_get_mi.tf

@@ -34,7 +34,9 @@ module "get_mi" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "GET_MI"
+  })
 }
 
 data "aws_iam_policy_document" "get_mi_lambda" {

infrastructure/terraform/components/api/module_lambda_get_status.tf

@@ -34,7 +34,9 @@ module "get_status" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "GET_STS"
+  })
 }
 
 data "aws_iam_policy_document" "get_status_lambda" {

infrastructure/terraform/components/api/module_lambda_letter_updates_transformer.tf

@@ -37,6 +37,7 @@ module "letter_updates_transformer" {
   lambda_env_vars = merge(local.common_lambda_env_vars, {
     EVENTPUB_SNS_TOPIC_ARN = "${module.eventpub.sns_topic.arn}",
     EVENT_SOURCE           = var.letter_event_source
+    LOG_REFERENCE          = "LTR_UPD_TFRM"
   })
 }
 

infrastructure/terraform/components/api/module_lambda_mi_updates_transformer.tf

@@ -37,6 +37,7 @@ module "mi_updates_transformer" {
 
   lambda_env_vars = merge(local.common_lambda_env_vars, {
     EVENTPUB_SNS_TOPIC_ARN = "${module.eventpub.sns_topic.arn}"
+    LOG_REFERENCE          = "MI_UPD_TFRM"
   })
 }
 

infrastructure/terraform/components/api/module_lambda_patch_letter.tf

@@ -35,7 +35,8 @@ module "patch_letter" {
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
   lambda_env_vars = merge(local.common_lambda_env_vars, {
-    QUEUE_URL = module.amendments_queue.sqs_queue_url
+    QUEUE_URL     = module.amendments_queue.sqs_queue_url
+    LOG_REFERENCE = "PTCH_LTRS"
   })
 }
 

infrastructure/terraform/components/api/module_lambda_post_letters.tf

@@ -35,8 +35,9 @@ module "post_letters" {
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
   lambda_env_vars = merge(local.common_lambda_env_vars, {
-    QUEUE_URL = module.amendments_queue.sqs_queue_url,
-    MAX_LIMIT = var.max_get_limit
+    QUEUE_URL     = module.amendments_queue.sqs_queue_url,
+    MAX_LIMIT     = var.max_get_limit
+    LOG_REFERENCE = "PST_LTRS"
   })
 }
 

infrastructure/terraform/components/api/module_lambda_post_mi.tf

@@ -34,7 +34,9 @@ module "post_mi" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "PST_MI"
+  })
 }
 
 data "aws_iam_policy_document" "post_mi_lambda" {

infrastructure/terraform/components/api/module_lambda_supplier_allocator.tf

@@ -38,6 +38,7 @@ module "supplier_allocator" {
     UPSERT_LETTERS_QUEUE_URL   = module.sqs_letter_updates.sqs_queue_url,
     SUPPLIER_ALLOCATOR_DLQ_URL = module.sqs_supplier_allocator.sqs_dlq_url,
     IDEMPOTENCY_TABLE_NAME     = aws_dynamodb_table.idempotency.name
+    LOG_REFERENCE              = "SUP_ALLOC"
   })
 }
 

infrastructure/terraform/components/api/module_lambda_supplier_config_ingress.tf

@@ -34,7 +34,9 @@ module "supplier_config_ingress" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "SUP_CFG_ING"
+  })
 }
 
 data "aws_iam_policy_document" "supplier_config_ingress_lambda" {

infrastructure/terraform/components/api/module_lambda_supplier_mock.tf

@@ -40,6 +40,7 @@ module "supplier_mock" {
     GET_LETTERS_FUNCTION_NAME       = module.get_letters.function_name
     PATCH_LETTER_FUNCTION_NAME      = module.patch_letter.function_name
     SUPPLIER_MOCK_CONFIG_PARAM_NAME = aws_ssm_parameter.supplier_mock_config[0].name
+    LOG_REFERENCE                   = "SUP_MCK"
   })
 }
 

infrastructure/terraform/components/api/module_lambda_update_letter_queue.tf

@@ -34,7 +34,9 @@ module "update_letter_queue" {
   log_destination_arn       = local.destination_arn
   log_subscription_role_arn = local.acct.log_subscription_role_arn
 
-  lambda_env_vars = merge(local.common_lambda_env_vars, {})
+  lambda_env_vars = merge(local.common_lambda_env_vars, {
+    LOG_REFERENCE = "UPD_LTR_QUE"
+  })
 }
 
 data "aws_iam_policy_document" "update_letter_queue_lambda" {

infrastructure/terraform/components/api/module_lambda_upsert_letter.tf

@@ -36,6 +36,7 @@ module "upsert_letter" {
 
   lambda_env_vars = merge(local.common_lambda_env_vars, {
     IDEMPOTENCY_TABLE_NAME = aws_dynamodb_table.idempotency.name
+    LOG_REFERENCE          = "UPST_LTR"
   })
 }
 

internal/helpers/src/logger.ts

@@ -2,20 +2,38 @@ import pino, { Logger } from "pino";
 
 export type LoggerOptions = {
   logLevel?: string;
+  logReference?: string;
 };
 
 /**
  * Creates a configured pino logger instance for use across lambdas.
  *
  * @param options - Optional configuration for the logger
  * @param options.logLevel - The log level (defaults to "info")
+ * @param options.logReference - Optional reference value to include on every log record
  * @returns A configured pino Logger instance
  */
 export function createLogger(options: LoggerOptions = {}): Logger {
-  const { logLevel = "info" } = options;
+  const { logLevel = "info", logReference } = options;
 
   return pino({
     level: logLevel,
+    redact: {
+      paths: ["logRef"],
+      remove: true,
+    },
+    mixin: (context) => {
+      const messageLogReference =
+        "logRef" in context && typeof context.logRef === "string"
+          ? context.logRef
+          : undefined;
+
+      if (logReference && messageLogReference) {
+        return { log_reference: `${logReference} - ${messageLogReference}` };
+      }
+
+      return logReference ? { log_reference: logReference } : {};
+    },
     formatters: {
       level: (label) => {
         return { level: label.toUpperCase() };

lambdas/api-handler/src/config/deps.ts

@@ -73,7 +73,10 @@ function createMIRepository(log: Logger, environment: EnvVars): MIRepository {
 }
 
 export function createDependenciesContainer(): Deps {
-  const log = createLogger({ logLevel: envVars.PINO_LOG_LEVEL });
+  const log = createLogger({
+    logLevel: envVars.PINO_LOG_LEVEL,
+    logReference: envVars.LOG_REFERENCE,
+  });
 
   return {
     s3Client: new S3Client(),

lambdas/api-handler/src/config/env.ts

@@ -16,6 +16,7 @@ const EnvVarsSchema = z.object({
   PINO_LOG_LEVEL: z.coerce.string().optional(),
   EVENT_SOURCE: z.string(),
   SNS_TOPIC_ARN: z.string(),
+  LOG_REFERENCE: z.string().optional(),
 });
 
 export type EnvVars = z.infer<typeof EnvVarsSchema>;

lambdas/api-handler/src/config/log-references.ts

@@ -0,0 +1,96 @@
+const LogRefs = {
+  HEALTHCHECK_PASSED: {
+    code: "001-HEALTHCHECK",
+    description: "Healthcheck passed",
+  },
+  UNEXPECTED_QUERY_PARAMETERS: {
+    code: "002-UNEXPECTED-PARAMS",
+    description: "Unexpected query parameter(s) present",
+  },
+  LIMIT_NOT_NUMBER: {
+    code: "003-NOT-NUMBER",
+    description: "limit parameter is not a number",
+  },
+  LIMIT_INVALID: {
+    code: "004-LIMIT-INVALID",
+    description: "Limit value is invalid",
+  },
+  PENDING_LETTERS_FETCHED: {
+    code: "005-PENDING-FETCHED",
+    description: "Pending letters successfully fetched",
+  },
+  LETTER_FETCHED: {
+    code: "006-LETTER-FETCHED",
+    description: "Letter successfully fetched by id",
+  },
+  PRESIGNED_URL_GENERATED: {
+    code: "007-URL-GENERATED",
+    description: "Generated presigned URL",
+  },
+  PATCH_LETTER_RECEIVED: {
+    code: "008-PATCH-LETTER",
+    description: "Received patch letter request",
+  },
+  POST_LETTERS_RECEIVED: {
+    code: "009-POST-LETTERS",
+    description: "Received post letters request",
+  },
+  ENQUEUED_LETTER_UPDATES: {
+    code: "010-UPDATES-QUEUED",
+    description: "Enqueued letter updates",
+  },
+  SOME_BATCH_ENTRIES_FAILED: {
+    code: "011-BATCH-FAILED",
+    description: "Some batch entries failed",
+  },
+  ERROR_ENQUEUING_LETTER_STATUS_UPDATES: {
+    code: "012-ENQUEUE-ERROR",
+    description: "Error enqueuing letter status updates",
+  },
+  LETTER_STATUS_UPDATE_SENT: {
+    code: "013-STATUS-SENT",
+    description: "Sent letter status update via topic",
+  },
+  LETTER_STATUS_UPDATE_ERROR: {
+    code: "014-STATUS-ERROR",
+    description: "Error processing letter status update",
+  },
+  MI_RETRIEVED: {
+    code: "015-MI-RETRIEVED",
+    description: "Retrieved management information",
+  },
+  MI_POSTED: {
+    code: "016-MI-POSTED",
+    description: "Posted management information",
+  },
+  VALIDATION_ERROR: {
+    code: "017-VALIDATION-ERROR",
+    description: "Validation error",
+  },
+  NOT_FOUND_ERROR: {
+    code: "018-NOT-FOUND-ERROR",
+    description: "Not found error",
+  },
+  INTERNAL_SERVER_ERROR: {
+    code: "019-SERVER-ERROR",
+    description: "Internal server error",
+  },
+  INTERNAL_SERVER_ERROR_NON_ERROR: {
+    code: "020-SERVER-ERROR-NON-ERROR",
+    description: "Internal server error (non-Error thrown)",
+  },
+  STATUS_ENDPOINT_ERROR: {
+    code: "021-ENDPOINT-ERROR",
+    description: "Status endpoint error, services not available",
+  },
+  METRIC: {
+    code: "022-METRIC",
+    description: "Metric emitted",
+  },
+  ERR_METRIC: {
+    code: "023-ERR-METRIC",
+    description: "Error metric emitted",
+  },
+};
+
+export default LogRefs;

lambdas/api-handler/src/handlers/__tests__/amendment-event-transformer.test.ts

@@ -120,7 +120,7 @@
             TopicArn: mockedDeps.env.SNS_TOPIC_ARN,
             Message: JSON.stringify(
               mapLetterToCloudEvent(
                 updateLetterCommands[i] as Letter,
                 mockedDeps.env.EVENT_SOURCE,
               ),
             ),
@@ -149,6 +149,7 @@
     );
 
     expect(mockedDeps.logger.error).toHaveBeenCalledWith({
+      logRef: "014-STATUS-ERROR",
       description: "Error processing letter status update",
       err: mockError,
       messageId: "mid-id2",

lambdas/api-handler/src/handlers/amendment-event-transformer.ts

@@ -10,6 +10,7 @@ import {
   UpdateLetterCommandSchema,
 } from "../contracts/letters";
 import { Deps } from "../config/deps";
+import LogRefs from "../config/log-references";
 
 export default function createTransformAmendmentEventHandler(
   deps: Deps,
@@ -37,7 +38,8 @@ export default function createTransformAmendmentEventHandler(
           buildSnsCommand(letterEvent, deps.env.SNS_TOPIC_ARN),
         );
         deps.logger.info({
-          description: "Sent letter status update via topic",
+          logRef: LogRefs.LETTER_STATUS_UPDATE_SENT.code,
+          description: LogRefs.LETTER_STATUS_UPDATE_SENT.description,
           letterId: updateLetterCommand.id,
           messageId: message.messageId,
           correlationId: message.messageAttributes.CorrelationId.stringValue,
@@ -49,7 +51,8 @@ export default function createTransformAmendmentEventHandler(
         );
       } catch (error) {
         deps.logger.error({
-          description: "Error processing letter status update",
+          logRef: LogRefs.LETTER_STATUS_UPDATE_ERROR.code,
+          description: LogRefs.LETTER_STATUS_UPDATE_ERROR.description,
           err: error,
           messageId: message.messageId,
           correlationId: message.messageAttributes.CorrelationId.stringValue,
@@ -90,7 +93,7 @@ function emitSuccessMetrics(
     unit: Unit.Count,
   };
   const emf = buildEMFObject("amendment-event-transformer", dimensions, metric);
-  logger.info(emf);
+  logger.info({ ...emf, logRef: LogRefs.METRIC.code });
 }
 
 function emitFailedItems(
@@ -111,6 +114,6 @@ function emitFailedItems(
       dimensions,
       metric,
     );
-    logger.info(emf);
+    logger.info({ ...emf, logRef: LogRefs.ERR_METRIC.code });
   }
 }

lambdas/api-handler/src/handlers/get-letter-data.ts

@@ -8,6 +8,7 @@ import { processError } from "../mappers/error-mapper";
 import ValidationError from "../errors/validation-error";
 import { getLetterDataUrl } from "../services/letter-operations";
 import type { Deps } from "../config/deps";
+import LogRefs from "../config/log-references";
 
 export default function createGetLetterDataHandler(
   deps: Deps,
@@ -40,7 +41,8 @@ export default function createGetLetterDataHandler(
         const presignedUrl = await getLetterDataUrl(supplierId, letterId, deps);
 
         deps.logger.info({
-          description: "Generated presigned URL",
+          logRef: LogRefs.PRESIGNED_URL_GENERATED.code,
+          description: LogRefs.PRESIGNED_URL_GENERATED.description,
           supplierId,
           letterId,
           correlationId: commonIds.value.correlationId,