Auto instrumentation hooks for PHP Session

.github/workflows/php.yml

@@ -50,6 +50,7 @@ jobs:
           'Instrumentation/Psr16',
           'Instrumentation/Psr18',
           'Instrumentation/ReactPHP',
+          'Instrumentation/Session', 
           'Instrumentation/Slim',
           'Instrumentation/Symfony',
           'Instrumentation/Yii',
@@ -82,6 +83,8 @@ jobs:
             php-version: 8.1
           - project: 'Instrumentation/PostgreSql'
             php-version: 8.1
+          - project: 'Instrumentation/Session'
+            php-version: 8.1
     steps:
     - uses: actions/checkout@v4
 

.gitsplit.yml

@@ -60,6 +60,8 @@ splits:
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-auto-psr18.git"
   - prefix: "src/Instrumentation/ReactPHP"
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-auto-reactphp.git"
+  - prefix: "src/Instrumentation/Session"
+    target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-auto-php-session.git"
   - prefix: "src/Instrumentation/Slim"
     target: "https://${GH_TOKEN}@github.com/opentelemetry-php/contrib-auto-slim.git"
   - prefix: "src/Instrumentation/Symfony"

composer.json

@@ -40,6 +40,7 @@
       "OpenTelemetry\\Contrib\\Instrumentation\\Psr16\\": "src/Instrumentation/Psr16/src",
       "OpenTelemetry\\Contrib\\Instrumentation\\Psr18\\": "src/Instrumentation/Psr18/src",
       "OpenTelemetry\\Contrib\\Instrumentation\\ReactPHP\\": "src/Instrumentation/ReactPHP/src",
+      "OpenTelemetry\\Contrib\\Instrumentation\\Session\\": "src/Instrumentation/Session/src",
       "OpenTelemetry\\Contrib\\Instrumentation\\Slim\\": "src/Instrumentation/Slim/src",
       "OpenTelemetry\\Contrib\\Instrumentation\\Symfony\\": "src/Instrumentation/Symfony/src",
       "OpenTelemetry\\Contrib\\Instrumentation\\Wordpress\\": "src/Instrumentation/Wordpress/src",
@@ -81,6 +82,7 @@
       "src/Instrumentation/Psr16/_register.php",
       "src/Instrumentation/Psr18/_register.php",
       "src/Instrumentation/ReactPHP/_register.php",
+      "src/Instrumentation/Session/_register.php",
       "src/Instrumentation/Slim/_register.php",
       "src/Instrumentation/Symfony/_register.php",
       "src/Instrumentation/Wordpress/_register.php",
@@ -115,6 +117,7 @@
       "OpenTelemetry\\Instrumentation\\Psr14\\Tests\\": "src/Instrumentation/Psr14/tests",
       "OpenTelemetry\\Tests\\Instrumentation\\Psr16\\": "src/Instrumentation/Psr16/tests",
       "OpenTelemetry\\Tests\\Instrumentation\\ReactPHP\\": "src/Instrumentation/ReactPHP/tests",
+      "OpenTelemetry\\Tests\\Instrumentation\\Session\\": "src/Instrumentation/Session/tests",
       "OpenTelemetry\\Tests\\Instrumentation\\Slim\\": "src/Instrumentation/Slim/tests",
       "OpenTelemetry\\Tests\\Instrumentation\\Symfony\\tests\\": "src/Instrumentation/Symfony/tests",
       "OpenTelemetry\\Tests\\Instrumentation\\Wordpress\\": "src/Instrumentation/Wordpress/tests",
@@ -156,6 +159,7 @@
     "open-telemetry/opentelemetry-auto-psr16": "self.version",
     "open-telemetry/opentelemetry-auto-psr18": "self.version",
     "open-telemetry/opentelemetry-auto-reactphp": "self.version",
+    "open-telemetry/opentelemetry-auto-php-session": "self.version",
     "open-telemetry/opentelemetry-auto-slim": "self.version",
     "open-telemetry/opentelemetry-auto-symfony": "self.version",
     "open-telemetry/opentelemetry-auto-wordpress": "self.version",

src/Instrumentation/Session/.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

src/Instrumentation/Session/.gitignore

@@ -0,0 +1 @@
+/vendor/

src/Instrumentation/Session/.php-cs-fixer.php

@@ -0,0 +1,42 @@
+<?php
+$finder = PhpCsFixer\Finder::create()
+    ->exclude('vendor')
+    ->exclude('var/cache')
+    ->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);

src/Instrumentation/Session/README.md

@@ -0,0 +1,57 @@
+# PHP Session Auto-instrumentation for OpenTelemetry
+
+This package provides auto-instrumentation for PHP's native session functions.
+
+## Installation
+
+```bash
+composer require open-telemetry/opentelemetry-auto-php-session
+```
+
+## Usage
+
+The instrumentation hooks into PHP's native session functions to provide tracing capabilities. It automatically creates spans for session operations like `session_start()` and `session_destroy()`.
+
+```php
+<?php
+// Make sure to initialize the OpenTelemetry SDK before using sessions
+// ...
+
+// Register the PHP Session instrumentation
+\OpenTelemetry\Contrib\Instrumentation\PhpSession\PhpSessionInstrumentation::register();
+
+// Now any session operations will be automatically traced
+session_start();
+// ... your code ...
+session_destroy();
+```
+
+## Spans and Attributes
+
+### session.start
+
+When `session_start()` is called, a span named `session.start` is created with the following attributes:
+
+- `code.function_name`: The function name (`session_start`)
+- `code.file_path`: The file path where the function was called
+- `code.line_number`: The line number where the function was called
+- `session.options.*`: Any options passed to `session_start()`
+- `session.id`: The session ID (if session was successfully started)
+- `session.name`: The session name (if session was successfully started)
+- `session.status`: Either "active" or "inactive"
+- `session.cookie.*`: Session cookie parameters
+
+### session.destroy
+
+When `session_destroy()` is called, a span named `session.destroy` is created with the following attributes:
+
+- `code.function_name`: The function name (`session_destroy`)
+- `code.file_path`: The file path where the function was called
+- `code.line_number`: The line number where the function was called
+- `session.id`: The session ID (if available)
+- `session.name`: The session name (if available)
+- `session.destroy.success`: Boolean indicating if the session was successfully destroyed
+
+## License
+
+Apache 2.0

src/Instrumentation/Session/_register.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+use OpenTelemetry\Contrib\Instrumentation\Session\PhpSessionInstrumentation;
+use OpenTelemetry\SDK\Sdk;
+
+if (class_exists(Sdk::class) && Sdk::isInstrumentationDisabled(PhpSessionInstrumentation::NAME) === true) {
+    return;
+}
+
+if (extension_loaded('opentelemetry') === false) {
+    trigger_error('The opentelemetry extension must be loaded in order to autoload the OpenTelemetry IO auto-instrumentation', E_USER_WARNING);
+
+    return;
+}
+
+PhpSessionInstrumentation::register();

src/Instrumentation/Session/composer.json

@@ -0,0 +1,32 @@
+{
+    "name": "open-telemetry/opentelemetry-auto-php-session",
+    "description": "OpenTelemetry auto-instrumentation for PHP Session functions",
+    "keywords": ["opentelemetry", "otel", "open-telemetry", "tracing", "php", "session"],
+    "type": "library",
+    "homepage": "https://opentelemetry.io/docs/php",
+    "readme": "./README.md",
+    "license": "Apache-2.0",
+    "require": {
+        "php": "^8.2",
+	"ext-opentelemetry": "*",
+        "ext-session": "*",
+        "open-telemetry/api": "^1.0",
+        "open-telemetry/sem-conv": "^1.0"
+    },
+    "autoload": {
+        "psr-4": {
+            "OpenTelemetry\\Contrib\\Instrumentation\\PhpSession\\": "src/"
+        }
+    },
+    "require-dev": {
+        "friendsofphp/php-cs-fixer": "^3",
+        "phan/phan": "^5.0",
+        "php-http/mock-client": "*",
+        "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"
+    }
+}

src/Instrumentation/Session/phpstan.neon.dist

@@ -0,0 +1,9 @@
+includes:
+    - vendor/phpstan/phpstan-phpunit/extension.neon
+
+parameters:
+    tmpDir: var/cache/phpstan
+    level: 5
+    paths:
+        - src
+        - tests

src/Instrumentation/Session/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>

src/Instrumentation/Session/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>