From ef2318879bda56794bfb3b6d2fc963c65acb6fff Mon Sep 17 00:00:00 2001 From: stair Date: Tue, 29 Aug 2023 13:33:48 -0400 Subject: [PATCH] Initial FAQ, with hopefully more contributions in the future. --- docs/FAQ.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 docs/FAQ.md diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 000000000..18bc66603 --- /dev/null +++ b/docs/FAQ.md @@ -0,0 +1,29 @@ +# Frequently Asked Questions (FAQ) + +## Stream Modality + +Questions related to stream modality (e.g., [MultiStreamTracker][multi-stream-tracker]). + +### What is the impact of transitioning my KCL app from single-stream to multi-stream? + +This answer assumes the [StreamTracker][stream-tracker] implementation is being changed. +From KCL's perspective, there is no modality change by decreasing a multi-stream tracker from `N` streams to `1` stream. + +The DDB `leaseKey`, used to persist metadata including lease checkpoint, has a modality-dependent format: + +| Modality | `leaseKey` Format | +|---------------|---------------------------------------------------------------| +| single-stream | `` | +| multi-stream | `:::` | + +Transitioning an app -- either from single- to multi-, or vice versa -- creates a backwards-incompatible expectation on the `leaseKey`. +As a result, a KCL app will be blind to any `leaseKey`, and its checkpoint, that does not match the expected format. + +## Resources + +For additional information, please consider reading: +* https://docs.aws.amazon.com/streams/latest/dev/kcl-migration.html +* https://docs.aws.amazon.com/streams/latest/dev/shared-throughput-kcl-consumers.html + +[multi-stream-tracker]: /amazon-kinesis-client/src/main/java/software/amazon/kinesis/processor/MultiStreamTracker.java +[stream-tracker]: /amazon-kinesis-client/src/main/java/software/amazon/kinesis/processor/StreamTracker.java \ No newline at end of file