Feature request: Support for `manualSegment` in `captureAWSv3Client()`

[Jhamtanidev]

Use case

✨ Feature Request: Support for manualSegment in captureAWSv3Client()

Summary

Currently, the Tracer.captureAWSv3Client() method in AWS Lambda Powertools for TypeScript only accepts a single argument — the AWS SDK v3 client instance. This restricts users from passing a manual X-Ray segment or subsegment, which is supported in the underlying aws-xray-sdk-core via:

captureAWSv3Client<T>(client: T, segment?: SegmentLike): T

For use cases that require precise control over segment context — such as batch processing — this limitation makes trace hierarchy management difficult.

---

Use Case

When processing events using processPartialResponse() or similar batch utilities, each item may require a dedicated subsegment. The ability to pass this subsegment to captureAWSv3Client() ensures AWS SDK calls are correctly nested within the item’s trace. Without this, SDK calls may attach to incorrect segments or appear disconnected in X-Ray.

---

Contribution

I'm open to contributing a pull request if this enhancement aligns with the maintainers’ vision for the library.

Solution/User Experience

Proposed Solution

Update the Tracer.captureAWSv3Client() method to accept an optional second parameter for a manual SegmentLike. This would internally forward both arguments to the X-Ray SDK’s native method, preserving existing behavior while enhancing flexibility:

captureAWSv3Client<T>(client: T, segment?: SegmentLike): T

This change would remain backward compatible and enable more advanced tracing scenarios.

---

Alternative solutions

Using the X-Ray SDK directly. This bypasses Powertools but loses consistency and built-in annotations.
Subclassing the Tracer to reintroduce the missing parameter. Functional, but not ideal for long-term maintainability.

Acknowledgment

• This feature request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[boring-cyborg]

Thanks for opening your first issue here! We'll come back to you as soon as we can.
In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

[dreamorosi]

Hi @Jhamtanidev, thank you for taking the time to open this issue and for your patience with the discussion at #4185.

I've been working on creating a PoC for both the discussion and the issue and I am not sure adding this feature would address your concern. I've left an answer with more details on why the AWS X-Ray SDK is unable to keep track of these parallel promises, so in this answer I'll focus on the feature request only.

While it's true that the captureAWSClient function from the X-Ray SDK accepts a second optional parameter I don't know that it'll work in this context. Looking at the implementation of this function I see two issues:

• the instrumentation of a client is done via a middleware stack and each call to captureAWSClient removes previous copies of the same middleware (source)
• both the doc string (source) and actual implementation (source) point towards the fact that this second optional segment parameter is used only when running in manual mode. By default the X-Ray SDK works in automatic mode when running in AWS Lambda, and Tracer assumes as such

While the first point could be mitigated by creating a dedicated instance of AWS SDK client for each record being processed, I don't see a good solution for the second point.

To test this, I deployed a Lambda function with the following code that uses the captureAWSClient function directly and passes a subsegment - this should be the use case you're suggesting if I understand correctly:

import {
	BatchProcessor,
	EventType,
	processPartialResponse,
} from "@aws-lambda-powertools/batch";
import xraySdk from "aws-xray-sdk-core";
const { captureAWSv3Client } = xraySdk;
import { Tracer } from "@aws-lambda-powertools/tracer";
import { captureLambdaHandler } from "@aws-lambda-powertools/tracer/middleware";
import middy from "@middy/core";
import type { Context, SQSEvent, SQSHandler, SQSRecord } from "aws-lambda";
import { S3Client, GetBucketAclCommand } from "@aws-sdk/client-s3";

const processor = new BatchProcessor(EventType.SQS);
const tracer = new Tracer({ serviceName: "serverlessAirline" });
const s3Client = new S3Client({ region: "us-east-1" });

const recordHandler = async (record: SQSRecord): Promise<void> => {
	const subsegment = tracer.getSegment()?.addNewSubsegment("### recordHandler");
	captureAWSv3Client(s3Client, subsegment); // passing the segment explicitly
	try {
		await s3Client.send(
			new GetBucketAclCommand({
				Bucket: record.body,
			}),
		);
	} catch (error) {
		subsegment?.addError(error as Error);
	} finally {
		subsegment?.close();
	}
};

export const handler: SQSHandler = middy(
	async (event: SQSEvent, context: Context) =>
		processPartialResponse(event, recordHandler, processor, {
			context,
		}),
).use(captureLambdaHandler(tracer));

This however still results in a broken lineage tree for traces

In short, I am unsure adding this feature would be beneficial at all for Tracer.

If I misunderstood something or you were able to see different results, please share more info so we can iterate on the feature request together. If we can find a solution I could be inclined to add it to the backlog (and thanks for offering to contribute it btw!).

[Jhamtanidev]

Hi @dreamorosi ,

Thank you for the detailed explanation and the PoC — I really appreciate the time and effort you've put into this.

You're absolutely right — the limitation around the second optional manualSegment parameter working only in manual mode (which isn't typically used in Lambda) is indeed a blocker for this request.

My original motivation for this feature was to improve trace attribution in parallelized async workloads (like processing multiple S3 records or DynamoDB streams in parallel). The assumption was that by explicitly passing the segment/subsegment to captureAWSv3Client, we could ensure AWS SDK calls are attached to the correct trace node, avoiding context loss. However, as your test and findings confirm, this won't work in Lambda's automatic mode as the SDK ignores the manual segment in that context.

Given that:

• This feature wouldn’t solve the parallel async context tracking problem in Lambda.
• Switching to manual mode would require overriding Powertools' assumptions, which may break other integrations or increase complexity.

I'm happy to close this feature request. I’ll look into restructuring my workload to either avoid deep parallelism or use captureAsyncFunc at smaller granularities to retain trace clarity.

Thanks again for validating this with a PoC and for the transparent communication!

Best regards,
@Jhamtanidev