From ecba4fa2c25d57cfd8d0877f7573c198e0993d47 Mon Sep 17 00:00:00 2001
From: Michael Sambol <sambol.michael@gmail.com>
Date: Thu, 26 Sep 2024 12:26:13 -0700
Subject: [PATCH] Add documentation around dlq

---
 packages/@aws-cdk/aws-pipes-alpha/lib/pipe.ts               | 6 ++++++
 .../@aws-cdk/aws-pipes-sources-alpha/lib/streamSource.ts    | 6 +++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/packages/@aws-cdk/aws-pipes-alpha/lib/pipe.ts b/packages/@aws-cdk/aws-pipes-alpha/lib/pipe.ts
index ca646c0d95f56..f350a38bff3fb 100644
--- a/packages/@aws-cdk/aws-pipes-alpha/lib/pipe.ts
+++ b/packages/@aws-cdk/aws-pipes-alpha/lib/pipe.ts
@@ -233,6 +233,12 @@ export class Pipe extends PipeBase {
      */
     const source = props.source.bind(this);
     props.source.grantRead(this.pipeRole);
+
+    /**
+     * An optional dead-letter queue stores any events that are not successfully delivered to
+     * a target after all retry attempts are exhausted. The IAM role needs permission to write
+     * events to the dead-letter queue, either an SQS queue or SNS topic.
+     */
     if (SourceWithDeadLetterTarget.isSourceWithDeadLetterTarget(props.source)) {
       props.source.grantPush(this.pipeRole, props.source.deadLetterTarget);
     }
diff --git a/packages/@aws-cdk/aws-pipes-sources-alpha/lib/streamSource.ts b/packages/@aws-cdk/aws-pipes-sources-alpha/lib/streamSource.ts
index 625f9961b7994..c15454aac85a9 100644
--- a/packages/@aws-cdk/aws-pipes-sources-alpha/lib/streamSource.ts
+++ b/packages/@aws-cdk/aws-pipes-sources-alpha/lib/streamSource.ts
@@ -17,7 +17,11 @@ export interface StreamSourceParameters {
   readonly batchSize?: number;
 
   /**
-    * Define the target queue to send dead-letter queue events to.
+    * Define the target to send dead-letter queue events to.
+    *
+    * The dead-letter queue stores any events that are not successfully delivered to a Pipes target after all retry attempts are exhausted.
+    * You can then resolve the issue that caused the failed invocations and replay the events at a later time.
+    * In some cases, such as when access is denied to a resource, events are sent directly to the dead-letter queue and are not retried.
     *
     * @see https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-pipes-pipe-pipesourcekinesisstreamparameters.html#cfn-pipes-pipe-pipesourcekinesisstreamparameters-deadletterconfig
     * @default - no dead-letter queue or topic