Skip to content

docs(operations): document nesting type observability trade-offs #194

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
lyushher wants to merge 2 commits into
base: main
Choose a base branch
from
+16 −4
Open

docs(operations): document nesting type observability trade-offs #194

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
36cc26c
docs(operations): explain nesting type trade-offs
lyushher May 26, 2026
378ea3d
docs(operations): explain nesting type trade-offs in map
lyushher May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/sdk-reference/operations/map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,8 +168,14 @@ Use map to apply the same operation to every item in a collection. Use
- `completionConfig` (optional) When to stop. Default: wait for all items.
- `serdes` (optional) Custom `Serdes` for the `BatchResult`.
- `itemSerdes` (optional) Custom `Serdes` for individual item results.
- `nesting` (optional) `NestingType.NESTED` (default) or `NestingType.FLAT`. `FLAT`
reduces operation overhead by ~30% at the cost of lower observability.
- `nesting` (optional) `NestingType.NESTED` (default) or `NestingType.FLAT`.
- With `NESTED`, child operations appear as separate scopes in the execution history,
making workflows easier to inspect and troubleshoot. This is recommended when
detailed execution visibility is important.
- With `FLAT`, child operations are flattened into the parent operation. This reduces
operation overhead by ~30%, but provides less detail in execution history and
observability tools such as CloudWatch logs. This is recommended for high-volume
workloads where minimizing overhead is more important than detailed tracing.

=== "Python"

Expand Down
10 changes: 8 additions & 2 deletions docs/sdk-reference/operations/parallel.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,8 +174,14 @@ execute the same operation concurrently for each item in a collection.
- `completionConfig` (optional) When to stop. Default: wait for all branches.
- `serdes` (optional) Custom `Serdes` for the `BatchResult`.
- `itemSerdes` (optional) Custom `Serdes` for individual branch results.
- `nesting` (optional) `NestingType.NESTED` (default) or `NestingType.FLAT`. `FLAT`
reduces operation overhead by ~30% at the cost of lower observability.
- `nesting` (optional) `NestingType.NESTED` (default) or `NestingType.FLAT`.
- With `NESTED`, child operations appear as separate scopes in the execution history,
making workflows easier to inspect and troubleshoot. This is recommended when
detailed execution visibility is important.
- With `FLAT`, child operations are flattened into the parent operation. This reduces
operation overhead by ~30%, but provides less detail in execution history and
observability tools such as CloudWatch logs. This is recommended for high-volume
workloads where minimizing overhead is more important than detailed tracing.

=== "Python"

Expand Down