Maintenance: mark `captureAWS` and `captureAWSClient` methods as deprecated in Tracer

[dreamorosi]

Summary

In March 2024, AWS announced that AWS SDK for JavaScript v2 will reach end-of-support in September 8, 2025. Additionally, the SDK has added warning logs to communicate the deprecation and encourage a migration to the newer AWS SDK for JavaScript v3.

In response to this announcement we should mark the Tracer methods used to instrument clients for this version, so that

Why is this needed?

So that Powertools customers relying on this feature have ample time to migrate from the method to and use the alternative captureAWSv3Client.

Which area does this relate to?

Tracer

Solution

Add a @deprecated notice on the methods found .

For example:

/**
 * Patch all AWS SDK v2 clients and create traces when your application makes calls to AWS services.
 *
 * If you want to patch a specific client use {@link captureAWSClient} and if you are using AWS SDK v3 use {@link captureAWSv3Client} instead.
 *
 * @see https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-nodejs-awssdkclients.html
 *
 * @example
 * ```typescript
 * import { Tracer } from '@aws-lambda-powertools/tracer';
 *
 * const tracer = new Tracer({ serviceName: 'serverlessAirline' });
 * const AWS = tracer.captureAWS(require('aws-sdk'));
 *
 * export const handler = async (_event: unknown, _context: unknown) => {
 *   ...
 * }
 * ```
 *
+ * @deprecated Use {@link captureAWSv3Client} instead.
 *
 * @param aws - AWS SDK v2 import
 * @returns AWS - Instrumented AWS SDK
 */
 public captureAWS<T>(aws: T): T {
   if (!this.isTracingEnabled()) return aws;

   return this.provider.captureAWS(aws);
 }

Additionally, we should also do the same and mark the ones here and here, like this:

 /**
 * Patch all AWS SDK v2 clients and create traces when your application makes calls to AWS services.
 *
+ * @deprecated
 *
 * @param awssdk - AWS SDK v2
 */
  public captureAWS<T>(awssdk: T): T {
   return captureAWS(awssdk);
 }

Acknowledgment

• [X] This 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.

[arnabrahman]

Sorry, I saw no assignees for this issue and just went ahead with the PR. @dreamorosi

[dreamorosi]

Hi @arnabrahman, nice to see you again! It's all good, thank you for taking this issue and submitting a PR!

Tomorrow morning I'll review it and get it merged 😊

[github-actions[bot]]

⚠️ COMMENT VISIBILITY WARNING ⚠️

This issue is now closed. Please be mindful that future comments are hard for our team to see.

If you need more assistance, please either tag a team member or open a new issue that references this one.

If you wish to keep having a conversation with other community members under this issue feel free to do so.