wip

Author: overtrue

README.md

@@ -10,24 +10,29 @@ This package provides a simple way to add [OpenTelemetry](https://opentelemetry.
 
 ## 🎯 Package Positioning
 
-### vs Official Auto-Instrumentation Package
+### Built on Official Auto-Instrumentation
 
-- **[Official Package](https://packagist.org/packages/open-telemetry/opentelemetry-auto-laravel)**: Automatic instrumentation using hooks, zero code changes required
-- **This Package**: Manual instrumentation with Laravel-style APIs, providing fine-grained control and additional features
+This package is **built on top of** the official [`open-telemetry/opentelemetry-auto-laravel`](https://packagist.org/packages/open-telemetry/opentelemetry-auto-laravel) package, providing additional manual instrumentation capabilities.
+
+### Package Relationship
+
+- **[Official Package](https://packagist.org/packages/open-telemetry/opentelemetry-auto-laravel)**: Foundation auto-instrumentation (automatically installed as dependency)
+- **This Package**: Additional manual instrumentation with Laravel-style APIs and enhanced features
 
 ### When to Use This Package
 
-- ✅ Need precise control over span attributes and lifecycle
-- ✅ Want to integrate deeply with Laravel events and services
+- ✅ Need both automatic AND manual instrumentation
+- ✅ Want precise control over span attributes and lifecycle
+- ✅ Need to integrate deeply with Laravel events and services
 - ✅ Prefer explicit instrumentation with Laravel facades
 - ✅ Need custom watchers and middleware
 - ✅ Building complex tracing scenarios
 
-### When to Use Official Auto-Instrumentation
+### When to Use Official Package Only
 
-- ✅ Want zero-code instrumentation
+- ✅ Want zero-code instrumentation only
 - ✅ Need basic request/response tracing
-- ✅ Prefer automatic framework detection
+- ✅ Prefer minimal setup
 
 ## Installation
 
@@ -135,20 +140,23 @@ OTEL_ENABLED=false
 OTEL_TRACES_EXPORTER=none
 ```
 
-### Alternative: Official Auto-Instrumentation Setup
+### Official Auto-Instrumentation Configuration
 
-If you prefer automatic instrumentation (requires `ext-opentelemetry` and official auto package):
-
-```bash
-composer require open-telemetry/opentelemetry-auto-laravel
-```
+This package automatically installs `open-telemetry/opentelemetry-auto-laravel` as a dependency. To enable the official auto-instrumentation features:
 
 ```dotenv
+# Enable PHP auto-instrumentation (requires ext-opentelemetry)
 OTEL_PHP_AUTOLOAD_ENABLED=true
 OTEL_PHP_TRACE_CLI_ENABLED=true
 OTEL_PROPAGATORS=baggage,tracecontext
+
+# Basic OpenTelemetry configuration (used by both packages)
+OTEL_SERVICE_NAME=my-laravel-app
+OTEL_TRACES_EXPORTER=console
 ```
 
+**Note**: The official package provides automatic instrumentation, while this package adds manual instrumentation capabilities on top.
+
 ## Usage
 
 ### Register the middleware

composer.json

@@ -16,19 +16,19 @@
     ],
     "require": {
         "php": ">=8.4",
-        "laravel/framework": "^12.0",
+        "laravel/framework": "^10.0|^11.0|^12.0",
         "open-telemetry/api": "^1.0",
         "open-telemetry/sdk": "^1.0",
-        "open-telemetry/exporter-otlp": "^1.0"
+        "open-telemetry/exporter-otlp": "^1.0",
+        "open-telemetry/opentelemetry-auto-laravel": "^1.1.1"
     },
     "require-dev": {
         "orchestra/testbench": "^9.0",
         "laravel/pint": "^1.15",
         "spatie/test-time": "^1.3"
     },
     "suggest": {
-        "ext-opentelemetry": "Required for zero-code instrumentation",
-        "open-telemetry/opentelemetry-auto-laravel": "For automatic instrumentation (alternative to manual instrumentation)"
+        "ext-opentelemetry": "Required for zero-code instrumentation"
     },
     "autoload-dev": {
         "psr-4": {

src/Support/TracerProviderManager.php

@@ -30,41 +30,45 @@ public static function getTracerProvider(): TracerProviderInterface
 
     private static function createTracerProvider(): TracerProviderInterface
     {
-        // 首先尝试使用全局的 TracerProvider
+        // 首先尝试使用全局的 TracerProvider（由 opentelemetry-auto-laravel 初始化）
         $globalProvider = Globals::tracerProvider();
 
         // 检查是否是有效的 TracerProvider（不是 NoopTracerProvider）
         if (! ($globalProvider instanceof NoopTracerProvider)) {
             return $globalProvider;
         }
 
-        // 如果全局 TracerProvider 无效且配置启用，创建一个基本的 SDK TracerProvider
-        if (config('otel.enabled', false) && config('otel.sdk.auto_initialize', true)) {
+        // 如果官方包没有初始化 TracerProvider，且我们的配置允许，提供一个基本的 fallback
+        if (config('otel.enabled', false) && config('otel.sdk.auto_initialize', false)) {
             try {
-                return self::createSDKTracerProvider();
+                if (config('app.debug')) {
+                    logger()->info('OpenTelemetry auto-laravel not initialized, creating fallback TracerProvider');
+                }
+
+                return self::createFallbackTracerProvider();
             } catch (\Throwable $e) {
-                // 如果创建失败，记录错误并使用 Noop Provider
                 if (config('app.debug')) {
-                    logger()->warning('Failed to create OpenTelemetry TracerProvider', [
+                    logger()->warning('Failed to create fallback OpenTelemetry TracerProvider', [
                         'error' => $e->getMessage(),
-                        'suggestion' => 'Check your OpenTelemetry configuration or install the opentelemetry extension',
+                        'suggestion' => 'Ensure opentelemetry-auto-laravel is properly configured or disable OTEL_SDK_AUTO_INITIALIZE',
                     ]);
                 }
             }
         }
 
-        // 返回 Noop TracerProvider
+        // 返回 Noop TracerProvider（这是预期的行为，当 OpenTelemetry 未配置时）
         return $globalProvider;
     }
 
-    private static function createSDKTracerProvider(): TracerProviderInterface
+    private static function createFallbackTracerProvider(): TracerProviderInterface
     {
         $resource = ResourceInfo::create(Attributes::create([
             'service.name' => config('otel.sdk.service_name', config('app.name', 'laravel-app')),
             'service.version' => config('otel.sdk.service_version', '1.0.0'),
             'telemetry.sdk.name' => 'opentelemetry',
             'telemetry.sdk.language' => 'php',
             'telemetry.sdk.version' => \Composer\InstalledVersions::getVersion('open-telemetry/sdk') ?? 'unknown',
+            'telemetry.auto.version' => 'manual-fallback', // 标识这是手动fallback
         ]));
 
         $tracerProviderBuilder = TracerProvider::builder()
@@ -96,11 +100,12 @@ private static function createSpanExporter(): ?\OpenTelemetry\SDK\Trace\SpanExpo
     private static function createOtlpExporter(): ?\OpenTelemetry\SDK\Trace\SpanExporterInterface
     {
         try {
-            $endpoint = config('otel.otlp.endpoint', 'http://localhost:4318');
-            $headers = config('otel.otlp.headers', []);
+            // 注意：这里只是一个基本实现
+            // 在实际使用中，用户应该通过 opentelemetry-auto-laravel 配置 OTLP
+            if (config('app.debug')) {
+                logger()->info('Using fallback console exporter instead of OTLP. For production OTLP, configure opentelemetry-auto-laravel properly.');
+            }
 
-            // 这里需要根据实际的 OTLP exporter 实现来创建
-            // 由于我们没有具体的 OTLP 配置，暂时返回 console exporter
             return new ConsoleSpanExporter;
         } catch (\Throwable $e) {
             logger()->warning('Failed to create OTLP exporter, falling back to console', [
@@ -130,6 +135,16 @@ public static function getProviderInfo(): array
             'class' => get_class($provider),
             'is_noop' => $provider instanceof NoopTracerProvider,
             'is_recording' => ! ($provider instanceof NoopTracerProvider),
+            'source' => $provider instanceof NoopTracerProvider ? 'noop' :
+                       (self::isUsingGlobalProvider() ? 'auto-laravel' : 'fallback'),
         ];
     }
+
+    private static function isUsingGlobalProvider(): bool
+    {
+        $globalProvider = Globals::tracerProvider();
+
+        return ! ($globalProvider instanceof NoopTracerProvider) &&
+               self::getTracerProvider() === $globalProvider;
+    }
 }