Update tracing docs highlighting functional API.

phipag · phipag · commit da3e96b71d2e · 2025-11-12T10:50:07.000+01:00
diff --git a/docs/core/tracing.md b/docs/core/tracing.md
@@ -20,7 +20,7 @@ a provides functionality to reduce the overhead of performing common tracing tas
 
 === "Maven"
 
-    ```xml hl_lines="3-7 16 18 24-27"
+    ```xml hl_lines="3-7 25-28"
     <dependencies>
         ...
         <dependency>
@@ -32,6 +32,7 @@ a provides functionality to reduce the overhead of performing common tracing tas
     </dependencies>
     ...
     <!-- configure the aspectj-maven-plugin to compile-time weave (CTW) the aws-lambda-powertools-java aspects into your project -->
+    <!-- Note: This AspectJ configuration is not needed when using the functional approach -->
     <build>
         <plugins>
             ...
@@ -73,22 +74,23 @@ a provides functionality to reduce the overhead of performing common tracing tas
 
 === "Gradle"
 
-    ```groovy hl_lines="3 11"
+    ```groovy hl_lines="3 11 12"
         plugins {
             id 'java'
-            id 'io.freefair.aspectj.post-compile-weaving' version '8.1.0'
+            id 'io.freefair.aspectj.post-compile-weaving' version '8.1.0' // Not needed when using the functional approach
         }
         
         repositories {
             mavenCentral()
         }
         
         dependencies {
-            aspect 'software.amazon.lambda:powertools-tracing:{{ powertools.version }}'
+            aspect 'software.amazon.lambda:powertools-tracing:{{ powertools.version }}' // Not needed when using the functional approach
+            implementation 'software.amazon.lambda:powertools-tracing:{{ powertools.version }}' // Use this instead of 'aspect' when using the functional approach
         }
         
-        sourceCompatibility = 11
-        targetCompatibility = 11
+        sourceCompatibility = 11 // or higher
+        targetCompatibility = 11 // or higher
     ```
 
 ## Initialization
@@ -118,11 +120,13 @@ The Powertools for AWS Lambda (Java) service name is used as the X-Ray namespace
 
 ### Lambda handler
 
-To enable Powertools for AWS Lambda (Java) tracing to your function add the `@Tracing` annotation to your `handleRequest` method or on
-any method will capture the method as a separate subsegment automatically. You can optionally choose to customize 
-segment name that appears in traces.
+You can enable tracing using either the `@Tracing` annotation or the functional API.
 
-=== "Tracing annotation"
+**With the `@Tracing` annotation**, add it to your `handleRequest` method or any method to capture it as a separate subsegment automatically. You can optionally customize the segment name that appears in traces.
+
+**With the functional API**, use `TracingUtils.withSubsegment()` to manually create subsegments without AspectJ configuration.
+
+=== "@Tracing annotation"
 
     ```java hl_lines="3 10 15"
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
@@ -146,6 +150,25 @@ segment name that appears in traces.
     }
     ```
 
+=== "Functional API"
+
+    ```java hl_lines="1 6 7 8 10 11 12"
+    import software.amazon.lambda.powertools.tracing.TracingUtils;
+
+    public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
+    
+        public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
+            TracingUtils.withSubsegment("businessLogic1", subsegment -> {
+                // Business logic 1
+            });
+    
+            TracingUtils.withSubsegment("businessLogic2", subsegment -> {
+                // Business logic 2
+            });
+        }
+    }
+    ```
+
 === "Custom Segment names"
 
     ```java hl_lines="3"
@@ -157,22 +180,25 @@ segment name that appears in traces.
         }
     ```
 
-When using this `@Tracing` annotation, Utility performs these additional tasks to ease operations:
+When using the `@Tracing` annotation, the utility performs these additional tasks to ease operations:
 
   * Creates a `ColdStart` annotation to easily filter traces that have had an initialization overhead.
   * Creates a `Service` annotation if service parameter or `POWERTOOLS_SERVICE_NAME` is set.
   * Captures any response, or full exceptions generated by the handler, and include as tracing metadata.
 
+By default, the `@Tracing` annotation uses `captureMode=ENVIRONMENT_VAR`, which means it will only record method responses and exceptions if you set
+the environment variables `POWERTOOLS_TRACER_CAPTURE_RESPONSE` and `POWERTOOLS_TRACER_CAPTURE_ERROR` to `true`. You can override this behavior by
+specifying a different `captureMode` to always record response, exception, both, or neither.
 
-By default, this annotation will automatically record method responses and exceptions. You can change the default behavior by setting
-the environment variables `POWERTOOLS_TRACER_CAPTURE_RESPONSE` and `POWERTOOLS_TRACER_CAPTURE_ERROR` as needed. Optionally, you can override behavior by
-different supported `captureMode` to record response, exception or both.
+!!! note
+    When using the functional API with `TracingUtils.withSubsegment()`, response and exception capture is not automatic. You can manually add metadata using `TracingUtils.putMetadata()` as needed.
 
-!!! warning "Returning sensitive information from your Lambda handler or functions, where `Tracing` is used?"
-    You can disable annotation from capturing their responses and exception as tracing metadata with **`captureMode=DISABLED`**
-    or globally by setting environment variables **`POWERTOOLS_TRACER_CAPTURE_RESPONSE`** and **`POWERTOOLS_TRACER_CAPTURE_ERROR`** to **`false`**
+!!! warning "Returning sensitive information from your Lambda handler or functions?"
+    When using the `@Tracing` annotation, you can disable it from capturing responses and exceptions as tracing metadata with **`captureMode=DISABLED`**
+    or globally by setting environment variables **`POWERTOOLS_TRACER_CAPTURE_RESPONSE`** and **`POWERTOOLS_TRACER_CAPTURE_ERROR`** to **`false`**.
+    When using the functional API, you have full control over what metadata is captured.
 
-=== "Disable on annotation"
+=== "@Tracing annotation - Disable on method"
 
     ```java hl_lines="3"
     public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
@@ -183,7 +209,7 @@ different supported `captureMode` to record response, exception or both.
         }
     ```
 
-=== "Disable Globally"
+=== "@Tracing annotation - Disable Globally"
 
     ```yaml hl_lines="11 12"
     Resources:
@@ -200,6 +226,20 @@ different supported `captureMode` to record response, exception or both.
                     POWERTOOLS_TRACER_CAPTURE_ERROR: false
     ```
 
+=== "Functional API"
+
+    ```java hl_lines="6 7 8"
+    import software.amazon.lambda.powertools.tracing.TracingUtils;
+
+    public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
+    
+        public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
+            TracingUtils.withSubsegment("businessLogic", subsegment -> {
+                // With functional API, you control what metadata is captured
+            });
+        }
+    ```
+
 ### Annotations & Metadata
 
 **Annotations** are key-values associated with traces and indexed by AWS X-Ray. You can use them to filter traces and to
@@ -272,32 +312,13 @@ specific fields from received event due to security.
     }
     ```
 
-## Utilities
-
-Tracing modules comes with certain utility method when you don't want to use annotation for capturing a code block
-under a subsegment, or you are doing multithreaded programming. Refer examples below.
+## Advanced usage
 
-=== "Functional Api"
+### Multi-threaded programming
 
-    ```java hl_lines="7 8 9 11 12 13"
-    import software.amazon.lambda.powertools.tracing.Tracing;
-    import software.amazon.lambda.powertools.tracing.TracingUtils;
-    
-    public class App implements RequestHandler<APIGatewayProxyRequestEvent, APIGatewayProxyResponseEvent> {
-    
-        public APIGatewayProxyResponseEvent handleRequest(APIGatewayProxyRequestEvent input, Context context) {
-             TracingUtils.withSubsegment("loggingResponse", subsegment -> {
-                // Some business logic
-             });
-    
-             TracingUtils.withSubsegment("localNamespace", "loggingResponse", subsegment -> {
-                // Some business logic
-             });
-        }
-    }
-    ```
+When working with multiple threads, you need to pass the trace entity to ensure proper trace context propagation.
 
-=== "Multi Threaded Programming"
+=== "Multi-threaded example"
 
     ```java hl_lines="7 9 10 11"
     import static software.amazon.lambda.powertools.tracing.TracingUtils.withEntitySubsegment;
@@ -317,25 +338,33 @@ under a subsegment, or you are doing multithreaded programming. Refer examples b
 
 ## Instrumenting SDK clients and HTTP calls
 
-Powertools for Lambda (Java) cannot intercept SDK clients instantiation to add X-Ray instrumentation. You should make sure to instrument the SDK clients explicitly. Refer details on
-[how to instrument SDK client with Xray](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html#xray-sdk-java-awssdkclients) 
-and [outgoing http calls](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html#xray-sdk-java-httpclients). For example:
+### AWS SDK for Java 2.x
 
-=== "LambdaHandler.java"
+Powertools for AWS Lambda (Java) includes the `aws-xray-recorder-sdk-aws-sdk-v2-instrumentor` library, which **automatically instruments all AWS SDK v2 clients** when you add the `powertools-tracing` dependency to your project. This means downstream calls to AWS services are traced without any additional configuration.
 
-    ```java hl_lines="1 2 7"
-    import com.amazonaws.xray.AWSXRay;
-    import com.amazonaws.xray.handlers.TracingHandler;
+If you need more control over which clients are instrumented, you can manually add the `TracingInterceptor` to specific clients:
+
+=== "Manual instrumentation (optional)"
+
+    ```java hl_lines="1 2 3 8 9 10 11"
+    import com.amazonaws.xray.interceptors.TracingInterceptor;
+    import software.amazon.awssdk.core.client.config.ClientOverrideConfiguration;
+    import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
 
     public class LambdaHandler {
-        private AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard()
-            .withRegion(Regions.fromName(System.getenv("AWS_REGION")))
-            .withRequestHandlers(new TracingHandler(AWSXRay.getGlobalRecorder()))
+        private DynamoDbClient client = DynamoDbClient.builder()
+            .region(Region.US_WEST_2)
+            .overrideConfiguration(ClientOverrideConfiguration.builder()
+                .addExecutionInterceptor(new TracingInterceptor())
+                .build()
+            )
             .build();
         // ...
     }
     ```
 
+For more details, refer to the [AWS X-Ray documentation on tracing AWS SDK calls](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-awssdkclients.html) and [outgoing HTTP calls](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java-httpclients.html).
+
 ## Testing your code
 
 When using `@Tracing` annotation, your Junit test cases needs to be configured to create parent Segment required by [AWS X-Ray SDK for Java](https://docs.aws.amazon.com/xray/latest/devguide/xray-sdk-java.html).
@@ -351,7 +380,7 @@ used internally via AWS X-Ray SDK to configure itself properly for lambda runtim
 
 === "Maven (pom.xml)"
 
-    ```xml hl_lines="4-13"
+    ```xml
     <build>
         ...
       <plugins>
@@ -370,9 +399,9 @@ used internally via AWS X-Ray SDK to configure itself properly for lambda runtim
     
     ```
 
-=== "Gradle (build.gradle) "
+=== "Gradle (build.gradle)"
     
-    ```json hl_lines="2-4"
+    ```json
     // Configures environment variable to avoid initialization of AWS X-Ray segments for each tests
     test {
         environment "LAMBDA_TASK_ROOT", "handler"
@@ -418,6 +447,3 @@ Below is an example configuration needed for each test case.
             // test logic
         }
     ```
-
-
-
