[aws-sdk]Added Initial auto-instrumentation library for aws-sdk (#361)

AsakerMohd · web-flow · commit fe1f35860b2c · 2025-06-10T11:21:38.000+10:00
* [aws-sdk]Added Initial auto-instrumentation library for aws-sdk

* Updated to use sem covs instead of hardcoding

* added to gitsplit

* added gitattributes file

* Updated to use the latest semcov 1.32

* Added aws tests to php.yml

* Updated composer for php 8.1 and fixed style issue

* Fixed psalm errors

* fixed styling again

* supress phan errors

* updated unit test to not require credentials

* updated comment messages
diff --git a/.github/workflows/php.yml b/.github/workflows/php.yml
@@ -22,6 +22,7 @@ jobs:
         project: [
           'Aws',
           'Context/Swoole',
+          'Instrumentation/AwsSdk',
           'Instrumentation/CakePHP',
           'Instrumentation/CodeIgniter',
           'Instrumentation/Curl',
diff --git a/.gitsplit.yml b/.gitsplit.yml
@@ -62,6 +62,8 @@ splits:
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-auto-yii.git"
   - prefix: "src/Instrumentation/Doctrine"
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-auto-doctrine.git"
+  - prefix: "src/Instrumentation/AwsSdk"
+    target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-auto-aws-sdk.git"
   - prefix: "src/Context/Swoole"
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/context-swoole.git"
   - prefix: "src/AutoInstrumentationInstaller"
diff --git a/src/Instrumentation/AwsSdk/.gitattributes b/src/Instrumentation/AwsSdk/.gitattributes
@@ -0,0 +1,12 @@
+* text=auto
+
+*.md diff=markdown
+*.php diff=php
+
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/.php-cs-fixer.php export-ignore
+/phpstan.neon.dist export-ignore
+/phpunit.xml.dist export-ignore
+/psalm.xml.dist export-ignore
+/tests export-ignore
diff --git a/src/Instrumentation/AwsSdk/.gitignore b/src/Instrumentation/AwsSdk/.gitignore
@@ -0,0 +1,2 @@
+/vendor/
+composer.lock
diff --git a/src/Instrumentation/AwsSdk/.phan/config.php b/src/Instrumentation/AwsSdk/.phan/config.php
diff --git a/src/Instrumentation/AwsSdk/.php-cs-fixer.php b/src/Instrumentation/AwsSdk/.php-cs-fixer.php
@@ -0,0 +1,45 @@
+<?php
+$finder = PhpCsFixer\Finder::create()
+    ->exclude('vendor')
+    ->exclude('tests/Unit81') //contains php8.1 syntax
+    ->exclude('var/cache')
+    ->exclude('tests/coverage')
+    ->in(__DIR__);
+
+$config = new PhpCsFixer\Config();
+return $config->setRules([
+    'concat_space' => ['spacing' => 'one'],
+    'declare_equal_normalize' => ['space' => 'none'],
+    'is_null' => true,
+    'modernize_types_casting' => true,
+    'ordered_imports' => true,
+    'php_unit_construct' => true,
+    'single_line_comment_style' => true,
+    'yoda_style' => false,
+    '@PSR2' => true,
+    'array_syntax' => ['syntax' => 'short'],
+    'blank_line_after_opening_tag' => true,
+    'blank_line_before_statement' => true,
+    'cast_spaces' => true,
+    'declare_strict_types' => true,
+    'type_declaration_spaces' => true,
+    'include' => true,
+    'lowercase_cast' => true,
+    'new_with_parentheses' => true,
+    'no_extra_blank_lines' => true,
+    'no_leading_import_slash' => true,
+    'echo_tag_syntax' => true,
+    'no_unused_imports' => true,
+    'no_useless_else' => true,
+    'no_useless_return' => true,
+    'phpdoc_order' => true,
+    'phpdoc_scalar' => true,
+    'phpdoc_types' => true,
+    'short_scalar_cast' => true,
+    'blank_lines_before_namespace' => true,
+    'single_quote' => true,
+    'trailing_comma_in_multiline' => true,
+    ])
+    ->setRiskyAllowed(true)
+    ->setFinder($finder);
+
diff --git a/src/Instrumentation/AwsSdk/README.md b/src/Instrumentation/AwsSdk/README.md
@@ -0,0 +1,25 @@
+[![Releases](https://img.shields.io/badge/releases-purple)](https://github.com/opentelemetry-php/contrib-auto-aws-sdk/releases)
+[![Issues](https://img.shields.io/badge/issues-pink)](https://github.com/open-telemetry/opentelemetry-php/issues)
+[![Source](https://img.shields.io/badge/source-contrib-green)](https://github.com/open-telemetry/opentelemetry-php-contrib/tree/main/src/Instrumentation/AwsSdk)
+[![Mirror](https://img.shields.io/badge/mirror-opentelemetry--php--contrib-blue)](https://github.com/opentelemetry-php/contrib-auto-aws-sdk)
+[![Latest Version](http://poser.pugx.org/open-telemetry/opentelemetry-auto-aws-sdk/v/unstable)](https://packagist.org/packages/open-telemetry/opentelemetry-auto-aws-sdk/)
+[![Stable](http://poser.pugx.org/open-telemetry/opentelemetry-auto-aws-sdk/v/stable)](https://packagist.org/packages/open-telemetry/opentelemetry-auto-aws-sdk/)
+
+This is a read-only subtree split of https://github.com/open-telemetry/opentelemetry-php-contrib.
+
+# OpenTelemetry AWS SDK auto-instrumentation
+Please read https://opentelemetry.io/docs/instrumentation/php/automatic/ for instructions on how to
+install and configure the extension and SDK.
+
+## Overview
+Auto-instrumentation hooks are registered via composer.
+
+* create spans automatically for each AWS SDK request that is sent
+
+## Configuration
+
+The extension can be disabled via [runtime configuration](https://opentelemetry.io/docs/instrumentation/php/sdk/#configuration):
+
+```shell
+OTEL_PHP_DISABLED_INSTRUMENTATIONS=aws-sdk
+```
diff --git a/src/Instrumentation/AwsSdk/_register.php b/src/Instrumentation/AwsSdk/_register.php
@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+use OpenTelemetry\Contrib\Instrumentation\AwsSdk\AwsSdkInstrumentation;
+use OpenTelemetry\SDK\Sdk;
+
+if (class_exists(Sdk::class)
+    && Sdk::isInstrumentationDisabled(AwsSdkInstrumentation::NAME)) {
+    return;
+}
+
+if (!extension_loaded('opentelemetry')) {
+    trigger_error(
+        'The opentelemetry extension must be loaded to use the AWS SDK auto‑instrumentation',
+        E_USER_WARNING
+    );
+
+    return;
+}
+
+AwsSdkInstrumentation::register();
diff --git a/src/Instrumentation/AwsSdk/composer.json b/src/Instrumentation/AwsSdk/composer.json
@@ -0,0 +1,48 @@
+{
+  "name": "open-telemetry/opentelemetry-auto-aws-sdk",
+  "description": "OpenTelemetry auto‑instrumentation for the AWS SDK",
+  "keywords": ["opentelemetry", "otel", "open-telemetry", "tracing", "aws-sdk", "instrumentation"],
+  "type": "library",
+  "homepage": "https://opentelemetry.io/docs/php",
+  "readme": "./README.md",
+  "license": "Apache-2.0",
+  "minimum-stability": "dev",
+  "prefer-stable": true,
+  "require": {
+    "php": "^8.1",
+    "aws/aws-sdk-php": "^3",
+    "ext-opentelemetry": "*",
+    "open-telemetry/api": "^1.0",
+    "open-telemetry/sem-conv": "^1.32"
+  },
+  "require-dev": {
+    "friendsofphp/php-cs-fixer": "^3",
+    "guzzlehttp/promises": "^2",
+    "nyholm/psr7": "*",
+    "phan/phan": "^5.0",
+    "phpstan/phpstan-mockery": "^1.1.0",
+    "phpstan/phpstan": "^1.1",
+    "phpstan/phpstan-phpunit": "^1.0",
+    "psalm/plugin-phpunit": "^0.19.2",
+    "open-telemetry/sdk": "^1.0",
+    "phpunit/phpunit": "^9.5",
+    "vimeo/psalm": "6.4.0"
+  },
+  "autoload": {
+    "psr-4": {
+      "OpenTelemetry\\Contrib\\Instrumentation\\AwsSdk\\": "src/"
+    },
+    "files": ["_register.php"]
+  },
+  "autoload-dev": {
+    "psr-4": {
+      "OpenTelemetry\\Tests\\Instrumentation\\AwsSdk\\": "tests/"
+    }
+  },
+  "config": {
+    "allow-plugins": {
+      "php-http/discovery": false,
+      "tbachert/spi": true
+    }
+  }
+}
diff --git a/src/Instrumentation/AwsSdk/phpstan.neon.dist b/src/Instrumentation/AwsSdk/phpstan.neon.dist
@@ -0,0 +1,12 @@
+includes:
+    - vendor/phpstan/phpstan-phpunit/extension.neon
+
+parameters:
+    tmpDir: var/cache/phpstan
+    level: 5
+    paths:
+        - src
+        - tests
+    excludePaths:
+        analyseAndScan:
+            - tests/Unit
diff --git a/src/Instrumentation/AwsSdk/phpunit.xml.dist b/src/Instrumentation/AwsSdk/phpunit.xml.dist
@@ -0,0 +1,47 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<phpunit
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.5/phpunit.xsd"
+    backupGlobals="false"
+    backupStaticAttributes="false"
+    cacheResult="false"
+    colors="false"
+    convertErrorsToExceptions="true"
+    convertNoticesToExceptions="true"
+    convertWarningsToExceptions="true"
+    forceCoversAnnotation="false"
+    processIsolation="false"
+    stopOnError="false"
+    stopOnFailure="false"
+    stopOnIncomplete="false"
+    stopOnSkipped="false"
+    stopOnRisky="false"
+    timeoutForSmallTests="1"
+    timeoutForMediumTests="10"
+    timeoutForLargeTests="60"
+    verbose="true">
+
+    <coverage processUncoveredFiles="true" disableCodeCoverageIgnore="false">
+        <include>
+            <directory>src</directory>
+        </include>
+    </coverage>
+
+    <php>
+        <ini name="date.timezone" value="UTC" />
+        <ini name="display_errors" value="On" />
+        <ini name="display_startup_errors" value="On" />
+        <ini name="error_reporting" value="E_ALL" />
+    </php>
+
+    <testsuites>
+        <testsuite name="unit">
+            <directory>tests/Unit</directory>
+        </testsuite>
+        <testsuite name="integration">
+            <directory>tests/Integration</directory>
+        </testsuite>
+    </testsuites>
+
+</phpunit>
diff --git a/src/Instrumentation/AwsSdk/psalm.xml.dist b/src/Instrumentation/AwsSdk/psalm.xml.dist
@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<psalm
+    errorLevel="3"
+    cacheDirectory="var/cache/psalm"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xmlns="https://getpsalm.org/schema/config"
+    xsi:schemaLocation="https://getpsalm.org/schema/config vendor/vimeo/psalm/config.xsd">
+    <projectFiles>
+        <directory name="src"/>
+        <directory name="tests"/>
+    </projectFiles>
+    <plugins>
+        <pluginClass class="Psalm\PhpUnitPlugin\Plugin"/>
+    </plugins>
+</psalm>
diff --git a/src/Instrumentation/AwsSdk/src/AwsSdkInstrumentation.php b/src/Instrumentation/AwsSdk/src/AwsSdkInstrumentation.php
@@ -0,0 +1,91 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenTelemetry\Contrib\Instrumentation\AwsSdk;
+
+use Aws\AwsClient;
+use Aws\Exception\AwsException;
+use Aws\ResultInterface;
+use OpenTelemetry\API\Instrumentation\CachedInstrumentation;
+use OpenTelemetry\API\Trace\Span;
+use OpenTelemetry\API\Trace\SpanKind;
+use OpenTelemetry\API\Trace\StatusCode;
+use OpenTelemetry\Context\Context;
+use function OpenTelemetry\Instrumentation\hook;
+use OpenTelemetry\SemConv\TraceAttributes;
+
+/** @psalm-suppress UnusedClass */
+final class AwsSdkInstrumentation
+{
+    /** @psalm-suppress ArgumentTypeCoercion */
+    public const NAME = 'aws-sdk';
+
+    public static function register(): void
+    {
+        $inst = new CachedInstrumentation(
+            'io.opentelemetry.contrib.php.aws-sdk',
+            null,
+            'https://opentelemetry.io/schemas/1.32.0',
+        );
+
+        /**
+         * Intercept the low‑level `execute` call that actually
+         * performs the HTTP request and has the Command object.
+         */
+        /** @psalm-suppress UnusedFunctionCall */
+        hook(
+            AwsClient::class,
+            'execute',
+            pre: static function (
+                AwsClient $c,
+                array $params,
+                string $class,
+                string $function,
+                ?string $filename,
+                ?int $lineno
+            ) use ($inst) {
+                $cmd     = $params[0];
+                $builder = $inst->tracer()
+                    ->spanBuilder("{$c->getApi()->getServiceName()}.{$cmd->getName()}")
+                    ->setSpanKind(SpanKind::KIND_CLIENT)
+                    ->setAttribute(TraceAttributes::RPC_SYSTEM, 'aws-api')
+                    ->setAttribute(TraceAttributes::RPC_METHOD, $cmd->getName())
+                    ->setAttribute(TraceAttributes::RPC_SERVICE, $c->getApi()->getServiceName())
+                    ->setAttribute(TraceAttributes::CLOUD_REGION, $c->getRegion())
+                    ->setAttribute(TraceAttributes::CODE_FUNCTION_NAME, sprintf('%s::%s', $class, $function))
+                    ->setAttribute(TraceAttributes::CODE_FILE_PATH, $filename)
+                    ->setAttribute(TraceAttributes::CODE_LINE_NUMBER, $lineno);
+
+                $span   = $builder->startSpan();
+                Context::storage()->attach($span->storeInContext(Context::getCurrent()));
+            },
+            post: static function (
+                AwsClient $c,
+                array $params,
+                mixed $result,
+                ?\Throwable $ex
+            ) {
+                $scope = Context::storage()->scope();
+                if (!$scope) {
+                    return;
+                }
+                $span = Span::fromContext($scope->context());
+                $scope->detach();
+
+                if ($result instanceof ResultInterface && isset($result['@metadata'])) {
+                    $span->setAttribute(TraceAttributes::HTTP_RESPONSE_STATUS_CODE, $result['@metadata']['statusCode']); // @phan-suppress-current-line PhanTypeMismatchDimFetch
+                    $span->setAttribute(TraceAttributes::AWS_REQUEST_ID, $result['@metadata']['headers']['x-amz-request-id']); // @phan-suppress-current-line PhanTypeMismatchDimFetch
+                }
+                if ($ex) {
+                    if ($ex instanceof AwsException && $ex->getAwsRequestId() !== null) {
+                        $span->setAttribute(TraceAttributes::AWS_REQUEST_ID, $ex->getAwsRequestId());
+                    }
+                    $span->recordException($ex);
+                    $span->setStatus(StatusCode::STATUS_ERROR, $ex->getMessage());
+                }
+                $span->end();
+            }
+        );
+    }
+}
diff --git a/src/Instrumentation/AwsSdk/tests/Integration/AwsSdkInstrumentationTest.php b/src/Instrumentation/AwsSdk/tests/Integration/AwsSdkInstrumentationTest.php
diff --git a/src/Instrumentation/AwsSdk/tests/Unit/.gitkeep b/src/Instrumentation/AwsSdk/tests/Unit/.gitkeep
