feat: add OpenTelemetry tracing support

pom.xml

@@ -14,8 +14,8 @@
   -->
 
 <project xmlns="http://maven.apache.org/POM/4.0.0"
-    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
     <modelVersion>4.0.0</modelVersion>
 
     <groupId>software.amazon.lambda</groupId>
@@ -25,7 +25,8 @@
 
     <name>Powertools for AWS Lambda (Java) - Parent</name>
     <description>
-        A suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating custom metrics asynchronously easier.
+        A suite of utilities for AWS Lambda Functions that makes tracing with AWS X-Ray, structured logging and creating
+        custom metrics asynchronously easier.
     </description>
     <scm>
         <url>https://github.com/aws-powertools/powertools-lambda-java</url>
@@ -77,6 +78,7 @@
         <module>powertools-parameters/powertools-parameters-appconfig</module>
         <module>powertools-parameters/powertools-parameters-tests</module>
         <module>examples</module>
+        <module>powertools-tracing-opentelemetry</module>
     </modules>
 
     <properties>
@@ -119,6 +121,8 @@
         <junit-pioneer.version>2.3.0</junit-pioneer.version>
         <crac.version>1.5.0</crac.version>
         <native-maven-plugin.version>0.11.5</native-maven-plugin.version>
+        <opentelemetry-api.version>1.65.0</opentelemetry-api.version>
+        <opentelemetry.aws.xray.propagator.version>1.59.0-alpha</opentelemetry.aws.xray.propagator.version>
 
         <!-- As we have a .mvn directory at the root of the project, this will evaluate to the root directory
             regardless of where maven is run - sub-module, or root. -->
@@ -313,6 +317,26 @@
                 <artifactId>commons-lang3</artifactId>
                 <version>3.20.0</version>
             </dependency>
+            <dependency>
+                <groupId>io.opentelemetry</groupId>
+                <artifactId>opentelemetry-api</artifactId>
+                <version>${opentelemetry-api.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.opentelemetry</groupId>
+                <artifactId>opentelemetry-sdk</artifactId>
+                <version>${opentelemetry-api.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.opentelemetry</groupId>
+                <artifactId>opentelemetry-exporter-otlp</artifactId>
+                <version>${opentelemetry-api.version}</version>
+            </dependency>
+            <dependency>
+                <groupId>io.opentelemetry.contrib</groupId>
+                <artifactId>opentelemetry-aws-xray-propagator</artifactId>
+                <version>${opentelemetry.aws.xray.propagator.version}</version>
+            </dependency>
 
             <!-- Test dependencies -->
             <dependency>
@@ -393,6 +417,12 @@
                 <version>3.13.2</version>
                 <scope>test</scope>
             </dependency>
+            <dependency>
+                <groupId>io.opentelemetry</groupId>
+                <artifactId>opentelemetry-sdk-testing</artifactId>
+                <version>${opentelemetry-api.version}</version>
+                <scope>test</scope>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 
@@ -471,7 +501,8 @@
                             <enabled>true</enabled>
                             <options>
                                 <enableExperimentalPredefinedClasses>true</enableExperimentalPredefinedClasses>
-                                <enableExperimentalUnsafeAllocationTracing>true</enableExperimentalUnsafeAllocationTracing>
+                                <enableExperimentalUnsafeAllocationTracing>true
+                                </enableExperimentalUnsafeAllocationTracing>
                             </options>
                             <metadataCopy>
                                 <disabledStages>
@@ -692,7 +723,9 @@
                         <artifactId>maven-surefire-plugin</artifactId>
                         <configuration>
                             <environmentVariables>
-                                <JDK_JAVA_OPTIONS>--add-opens java.base/java.util=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED</JDK_JAVA_OPTIONS>
+                                <JDK_JAVA_OPTIONS>--add-opens java.base/java.util=ALL-UNNAMED --add-opens
+                                    java.base/java.lang=ALL-UNNAMED
+                                </JDK_JAVA_OPTIONS>
                             </environmentVariables>
                         </configuration>
                     </plugin>

powertools-common/src/main/java/software/amazon/lambda/powertools/common/internal/SystemWrapper.java

@@ -22,6 +22,10 @@ public static String getenv(String name) {
         return System.getenv(name);
     }
 
+    public static boolean containsKey(String key) {
+        return System.getenv().containsKey(key);
+    }
+
     public static String getProperty(String name) {
         return System.getProperty(name);
     }

powertools-tracing-opentelemetry/pom.xml

@@ -0,0 +1,151 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Copyright 2023 Amazon.com, Inc. or its affiliates.
+  ~ Licensed under the Apache License, Version 2.0 (the
+  ~ "License"); you may not use this file except in compliance
+  ~ with the License.  You may obtain a copy of the License at
+  ~     http://www.apache.org/licenses/LICENSE-2.0
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+  ~
+  -->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>powertools-tracing-opentelemetry</artifactId>
+    <packaging>jar</packaging>
+
+    <parent>
+        <groupId>software.amazon.lambda</groupId>
+        <artifactId>powertools-parent</artifactId>
+        <version>2.10.0</version>
+    </parent>
+
+    <name>Powertools for AWS Lambda (Java) - Tracing OpenTelemetry</name>
+    <description>
+        A suite of utilities for AWS Lambda Functions that makes tracing with OpenTelemetry, structured logging and
+        creating custom metrics asynchronously easier.
+    </description>
+
+    <dependencies>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-api</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-sdk</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-exporter-otlp</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>io.opentelemetry.contrib</groupId>
+            <artifactId>opentelemetry-aws-xray-propagator</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.aspectj</groupId>
+            <artifactId>aspectjrt</artifactId>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.lambda</groupId>
+            <artifactId>powertools-common</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>aws-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>sdk-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.amazonaws</groupId>
+            <artifactId>aws-lambda-java-core</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.amazonaws</groupId>
+            <artifactId>aws-lambda-java-events</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+        </dependency>
+
+        <!-- Test dependencies -->
+        <dependency>
+            <groupId>io.opentelemetry</groupId>
+            <artifactId>opentelemetry-sdk-testing</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.mockito</groupId>
+            <artifactId>mockito-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>software.amazon.lambda</groupId>
+            <artifactId>powertools-common</artifactId>
+            <version>${project.version}</version>
+            <type>test-jar</type>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-simple</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit-pioneer</groupId>
+            <artifactId>junit-pioneer</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.apache.commons</groupId>
+            <artifactId>commons-lang3</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.aspectj</groupId>
+            <artifactId>aspectjweaver</artifactId>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.assertj</groupId>
+            <artifactId>assertj-core</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <environmentVariables>
+                        <AWS_LAMBDA_INITIALIZATION_TYPE>on-demand</AWS_LAMBDA_INITIALIZATION_TYPE>
+                    </environmentVariables>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+</project>

powertools-tracing-opentelemetry/src/main/java/software/amazon/lambda/powertools/tracing/opentelemetry/CaptureMode.java

@@ -0,0 +1,32 @@
+package software.amazon.lambda.powertools.tracing.opentelemetry;
+
+/**
+ * Defines how method responses and errors are captured by tracing.
+ */
+public enum CaptureMode {
+
+    /**
+     * Capture response and errors according to environment variables.
+     */
+    ENVIRONMENT_VAR,
+
+    /**
+     * Capture the method response.
+     */
+    RESPONSE,
+
+    /**
+     * Capture errors thrown by the method.
+     */
+    ERROR,
+
+    /**
+     * Capture both the method response and errors.
+     */
+    RESPONSE_AND_ERROR,
+
+    /**
+     * Disable response and error capture.
+     */
+    DISABLED
+}

powertools-tracing-opentelemetry/src/main/java/software/amazon/lambda/powertools/tracing/opentelemetry/Tracing.java

@@ -0,0 +1,43 @@
+package software.amazon.lambda.powertools.tracing.opentelemetry;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation to enable OpenTelemetry tracing for the annotated method.
+ * Automatically creates and manages an OpenTelemetry span for the method invocation.
+ * <p>
+ * This annotation allows configuration of the namespace, span name, and capture mode
+ * for tracing purposes. If no explicit configuration is provided, default values are used.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface Tracing {
+    /**
+     * The namespace associated with the span.
+     *
+     * <p>If empty, the default Powertools service name is used.
+     *
+     * @return the namespace
+     */
+    String namespace() default "";
+
+    /**
+     * The name of the span.
+     *
+     * <p>If empty, the annotated method name is used.
+     *
+     * @return the span name
+     */
+    String spanName() default "";
+
+    /**
+     * Controls whether the method response and/or errors are captured
+     * as span data.
+     *
+     * @return the capture mode
+     */
+    CaptureMode captureMode() default CaptureMode.ENVIRONMENT_VAR;
+}