refact: cs

overtrue · overtrue · commit f0b6491bd47c · 2025-08-26T09:49:52.000+08:00
diff --git a/.cursor-rules b/.cursor-rules
@@ -133,3 +133,158 @@ src/
 - 遵循语义化版本管理
 
 记住：严格遵循这些规则，确保每次代码改动都是必要的、安全的和高效的。
+
+---
+
+# 开发指南
+
+## 开发理念
+
+### 核心信念
+
+- **渐进式进步优于大爆炸式改变** - 小而可编译、通过测试的改动
+- **从现有代码学习** - 实施前先学习和规划
+- **实用主义优于教条主义** - 适应项目现实
+- **清晰意图优于巧妙代码** - 选择无聊但明显的方案
+
+### 简单性意味着
+
+- 每个函数/类单一职责
+- 避免过早抽象
+- 没有巧妙技巧 - 选择无聊的解决方案
+- 如果需要解释，说明太复杂了
+
+## 开发流程
+
+### 1. 规划与分阶段
+
+将复杂工作分解为3-5个阶段。在 `IMPLEMENTATION_PLAN.md` 中记录：
+
+```markdown
+## 阶段 N: [名称]
+**目标**: [具体交付物]
+**成功标准**: [可测试的结果]
+**测试**: [具体测试用例]
+**状态**: [未开始|进行中|完成]
+```
+- 随着进度更新状态
+- 所有阶段完成后删除文件
+
+### 2. 实施流程
+
+1. **理解** - 研究代码库中的现有模式
+2. **测试** - 先写测试（红色）
+3. **实现** - 通过测试的最小代码（绿色）
+4. **重构** - 清理代码，保持测试通过
+5. **提交** - 清晰的消息，链接到计划
+
+### 3. 遇到困难时（3次尝试后）
+
+**关键**: 每个问题最多尝试3次，然后停止。
+
+1. **记录失败原因**:
+   - 尝试了什么
+   - 具体错误信息
+   - 认为失败的原因
+
+2. **研究替代方案**:
+   - 找到2-3个类似实现
+   - 注意使用的不同方法
+
+3. **质疑基础假设**:
+   - 这是正确的抽象级别吗？
+   - 可以分解为更小的问题吗？
+   - 有更简单的方法吗？
+
+4. **尝试不同角度**:
+   - 不同的库/框架功能？
+   - 不同的架构模式？
+   - 移除抽象而不是添加？
+
+## 技术标准
+
+### 架构原则
+
+- **组合优于继承** - 使用依赖注入
+- **接口优于单例** - 支持测试和灵活性
+- **显式优于隐式** - 清晰的数据流和依赖关系
+- **尽可能测试驱动** - 永远不要禁用测试，修复它们
+
+### 代码质量
+
+- **每次提交必须**:
+  - 成功编译
+  - 通过所有现有测试
+  - 包含新功能的测试
+  - 遵循项目格式/规范
+
+- **提交前**:
+  - 运行格式化工具/检查器
+  - 自我审查变更
+  - 确保提交消息解释"为什么"
+
+### 错误处理
+
+- 快速失败，包含描述性消息
+- 包含调试上下文
+- 在适当级别处理错误
+- 永远不要静默吞掉异常
+
+## 决策框架
+
+当存在多个有效方法时，基于以下因素选择：
+
+1. **可测试性** - 我能轻松测试这个吗？
+2. **可读性** - 6个月后有人能理解这个吗？
+3. **一致性** - 这符合项目模式吗？
+4. **简单性** - 这是最简单的可行解决方案吗？
+5. **可逆性** - 以后改变有多难？
+
+## 项目集成
+
+### 学习代码库
+
+- 找到3个类似功能/组件
+- 识别常见模式和约定
+- 尽可能使用相同的库/工具
+- 遵循现有测试模式
+
+### 工具使用
+
+- 使用项目现有的构建系统
+- 使用项目的测试框架
+- 使用项目的格式化/检查设置
+- 没有强烈理由不要引入新工具
+
+## 质量门禁
+
+### 完成定义
+
+- [ ] 测试编写并通过
+- [ ] 代码遵循项目约定
+- [ ] 没有格式化/检查警告
+- [ ] 提交消息清晰
+- [ ] 实现符合计划
+- [ ] 没有无问题编号的TODO
+
+### 测试指导原则
+
+- 测试行为，不是实现
+- 尽可能每个测试一个断言
+- 清晰的测试名称描述场景
+- 使用现有测试工具/助手
+- 测试应该是确定性的
+
+## 重要提醒
+
+**永远不要**:
+- 使用 `--no-verify` 绕过提交钩子
+- 禁用测试而不是修复它们
+- 提交无法编译的代码
+- 做假设 - 用现有代码验证
+
+**始终要**:
+- 增量提交工作代码
+- 随着进度更新计划文档
+- 从现有实现学习
+- 3次失败尝试后停止并重新评估
diff --git a/README.md b/README.md
@@ -90,6 +90,8 @@ You can completely enable or disable tracing for the entire application. This is
 ```
 Set `OTEL_ENABLED=false` in your `.env` file to disable all tracing.
 
+**Log Format**: All OpenTelemetry logs are prefixed with `[laravel-open-telemetry]` for easy identification and filtering.
+
 #### Filtering Requests and Headers
 
 You can control which requests are traced and which headers are recorded to enhance performance and protect sensitive data. All patterns support wildcards (`*`) and are case-insensitive.
diff --git a/src/Handlers/WorkerStartingHandler.php b/src/Handlers/WorkerStartingHandler.php
@@ -28,8 +28,6 @@ public function handle(WorkerStarting $event): void
         // Worker initialization logic can be added here
         // For example, setting up worker-specific spans or contexts
 
-        Log::debug('OpenTelemetry Octane: Worker starting handler called');
-
         // 验证OTEL环境变量
         $otelVars = [
             'OTEL_SERVICE_NAME',
@@ -39,14 +37,8 @@ public function handle(WorkerStarting $event): void
 
         foreach ($otelVars as $var) {
             if (! isset($_ENV[$var]) && ! isset($_SERVER[$var])) {
-                Log::warning('OpenTelemetry Octane: Missing required environment variable', [
-                    'variable' => $var,
-                ]);
-            } else {
-                $value = $_ENV[$var] ?? $_SERVER[$var] ?? 'unknown';
-                Log::debug('OpenTelemetry Octane: Environment variable configured', [
+                Log::warning('[laravel-open-telemetry] Octane: Missing required environment variable', [
                     'variable' => $var,
-                    'value' => $value,
                 ]);
             }
         }
diff --git a/src/Http/Middleware/TraceRequest.php b/src/Http/Middleware/TraceRequest.php
@@ -19,19 +19,9 @@ class TraceRequest
      */
     public function handle(Request $request, Closure $next)
     {
-        Log::debug('OpenTelemetry TraceRequest: Processing request initiated', [
-            'method' => $request->method(),
-            'path' => $request->path(),
-            'url' => $request->fullUrl(),
-        ]);
-
         // Check if request path should be ignored
         if (HttpAttributesHelper::shouldIgnoreRequest($request)) {
-            Log::debug('OpenTelemetry TraceRequest: Request path ignored - skipping tracing', [
-                'path' => $request->path(),
-            ]);
             Measure::disable();
-
             return $next($request);
         }
 
@@ -40,24 +30,13 @@ public function handle(Request $request, Closure $next)
 
         $span = Measure::startRootSpan(SpanNameHelper::http($request), [], $parentContext);
 
-        Log::debug('OpenTelemetry TraceRequest: Root span created successfully', [
-            'span_id' => $span->getContext()->getSpanId(),
-            'trace_id' => $span->getContext()->getTraceId(),
-        ]);
-
         try {
             // Set request attributes
             HttpAttributesHelper::setRequestAttributes($span, $request);
 
-            Log::debug('OpenTelemetry TraceRequest: Root span configured in Measure service');
-
             // Process request
             $response = $next($request);
 
-            Log::debug('OpenTelemetry TraceRequest: Request processing completed - setting response attributes', [
-                'status_code' => $response->getStatusCode(),
-            ]);
-
             // Set response attributes and status
             HttpAttributesHelper::setResponseAttributes($span, $response);
             HttpAttributesHelper::setSpanStatusFromResponse($span, $response);
@@ -68,7 +47,8 @@ public function handle(Request $request, Closure $next)
             return $response;
 
         } catch (Throwable $exception) {
-            Log::error('OpenTelemetry TraceRequest: Exception occurred during request processing', [
+            // Log exception for debugging purposes
+            Log::error('[laravel-open-telemetry] TraceRequest: Exception occurred during request processing', [
                 'exception' => $exception->getMessage(),
                 'file' => $exception->getFile(),
                 'line' => $exception->getLine(),
@@ -81,12 +61,8 @@ public function handle(Request $request, Closure $next)
 
             throw $exception;
         } finally {
-            Log::debug('OpenTelemetry TraceRequest: Finalizing span and cleaning up resources');
-
             // End span and detach scope
             Measure::endRootSpan();
-
-            Log::debug('OpenTelemetry TraceRequest: Processing completed successfully');
         }
     }
 }
diff --git a/src/OpenTelemetryServiceProvider.php b/src/OpenTelemetryServiceProvider.php
@@ -26,15 +26,9 @@ public function boot(): void
 
         // Check if OpenTelemetry is enabled
         if (! config('otel.enabled', true)) {
-            Log::debug('OpenTelemetry: Service provider registration skipped - OpenTelemetry is disabled');
-
             return;
         }
 
-        Log::debug('OpenTelemetry: Service provider initialization started', [
-            'config' => config('otel'),
-        ]);
-
         $this->registerCommands();
         $this->registerWatchers();
         $this->registerLifecycleHandlers();
@@ -60,7 +54,7 @@ public function register(): void
 
         $this->app->alias(TracerInterface::class, 'opentelemetry.tracer');
 
-        Log::debug('OpenTelemetry: Service provider registered successfully');
+        Log::debug('[laravel-open-telemetry] Service provider registered successfully');
     }
 
     /**
@@ -126,7 +120,7 @@ protected function registerMiddlewares(): void
             // Enable TraceId middleware globally by default
             if (config('otel.middleware.trace_id.global', true)) {
                 $kernel->pushMiddleware(AddTraceId::class);
-                Log::debug('OpenTelemetry: Middleware registered globally for automatic tracing');
+                Log::debug('[laravel-open-telemetry] Middleware registered globally for automatic tracing');
             }
         }
     }
diff --git a/src/Support/Measure.php b/src/Support/Measure.php
@@ -83,12 +83,6 @@ public function startRootSpan(string $name, array $attributes = [], ?ContextInte
         $scope = $span->storeInContext($parentContext)->activate();
         self::$rootScope = $scope;
 
-        Log::debug('OpenTelemetry: Starting root span', [
-            'name' => $name,
-            'attributes' => $attributes,
-            'trace_id' => $span->getContext()->getTraceId(),
-        ]);
-
         self::$rootSpan = $span;
 
         return $span;
@@ -242,7 +236,7 @@ public function tracer(): TracerInterface
         try {
             return $this->app->get(TracerInterface::class);
         } catch (Throwable $e) {
-            Log::error('OpenTelemetry: Tracer not found', [
+            Log::error('[laravel-open-telemetry] Tracer not found', [
                 'error' => $e->getMessage(),
                 'line' => $e->getLine(),
                 'file' => $e->getFile(),
diff --git a/src/Watchers/QueryWatcher.php b/src/Watchers/QueryWatcher.php
@@ -41,13 +41,6 @@ public function recordQuery(QueryExecuted $event): void
             'db.query.time_ms' => $event->time,
         ]);
 
-        Log::debug('OpenTelemetry: QueryWatcher: Span created', [
-            'span_id' => $span->getContext()->getSpanId(),
-            'trace_id' => $span->getContext()->getTraceId(),
-            'operation' => $this->getOperationName($event->sql),
-            'table' => $this->extractTableName($event->sql),
-        ]);
-
         $span->end($now);
     }
 
diff --git a/tests/Handlers/WorkerStartingHandlerTest.php b/tests/Handlers/WorkerStartingHandlerTest.php
@@ -69,14 +69,7 @@ public function test_handle_resets_state_and_logs_debug_info(): void
         $_ENV['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://localhost:4318';
         $_ENV['OTEL_EXPORTER_OTLP_PROTOCOL'] = 'http/protobuf';
 
-        // Mock Log facade
-        Log::shouldReceive('debug')
-            ->once()
-            ->with('OpenTelemetry Octane: Worker starting handler called');
-
-        Log::shouldReceive('debug')
-            ->times(3)
-            ->with('OpenTelemetry Octane: Environment variable configured', \Mockery::type('array'));
+        // Mock Log facade - no debug logs expected since we removed them
 
         $event = new WorkerStarting('app', 1);
 
@@ -108,14 +101,10 @@ public function test_handle_logs_warning_for_missing_environment_variables(): vo
         unset($_SERVER['OTEL_EXPORTER_OTLP_ENDPOINT']);
         unset($_SERVER['OTEL_EXPORTER_OTLP_PROTOCOL']);
 
-        // Mock Log facade
-        Log::shouldReceive('debug')
-            ->once()
-            ->with('OpenTelemetry Octane: Worker starting handler called');
-
+        // Mock Log facade - only warning logs expected
         Log::shouldReceive('warning')
             ->times(3)
-            ->with('OpenTelemetry Octane: Missing required environment variable', \Mockery::type('array'));
+            ->with('[laravel-open-telemetry] Octane: Missing required environment variable', \Mockery::type('array'));
 
         $event = new WorkerStarting('app', 1);
 
@@ -143,14 +132,7 @@ public function test_handle_reads_from_server_variables_when_env_not_available()
         $_SERVER['OTEL_EXPORTER_OTLP_ENDPOINT'] = 'http://server:4318';
         $_SERVER['OTEL_EXPORTER_OTLP_PROTOCOL'] = 'grpc';
 
-        // Mock Log facade
-        Log::shouldReceive('debug')
-            ->once()
-            ->with('OpenTelemetry Octane: Worker starting handler called');
-
-        Log::shouldReceive('debug')
-            ->times(3)
-            ->with('OpenTelemetry Octane: Environment variable configured', \Mockery::type('array'));
+        // Mock Log facade - no debug logs expected since we removed them
 
         $event = new WorkerStarting('app', 1);
 
diff --git a/tests/OpenTelemetryServiceProviderTest.php b/tests/OpenTelemetryServiceProviderTest.php
@@ -115,15 +115,11 @@ public function test_provider_logs_startup_and_registration()
     {
         // Mock Log facade
         Log::shouldReceive('debug')
-            ->with('OpenTelemetry: Service provider initialization started', Mockery::type('array'))
+            ->with('[laravel-open-telemetry] Service provider registered successfully')
             ->once();
 
         Log::shouldReceive('debug')
-            ->with('OpenTelemetry: Service provider registered successfully')
-            ->once();
-
-        Log::shouldReceive('debug')
-            ->with('OpenTelemetry: Middleware registered globally for automatic tracing')
+            ->with('[laravel-open-telemetry] Middleware registered globally for automatic tracing')
             ->once();
 
         // Create service provider

Original file line number	Diff line number	Diff line change
`@@ -26,15 +26,9 @@ public function boot(): void`
`26`	`26`
`27`	`27`	`// Check if OpenTelemetry is enabled`
`28`	`28`	`if (! config('otel.enabled', true)) {`
`29`		`- Log::debug('OpenTelemetry: Service provider registration skipped - OpenTelemetry is disabled');`
`30`		`-`
`31`	`29`	`return;`
`32`	`30`	`}`
`33`	`31`
`34`		`- Log::debug('OpenTelemetry: Service provider initialization started', [`
`35`		`- 'config' => config('otel'),`
`36`		`- ]);`
`37`		`-`
`38`	`32`	`$this->registerCommands();`
`39`	`33`	`$this->registerWatchers();`
`40`	`34`	`$this->registerLifecycleHandlers();`
`@@ -60,7 +54,7 @@ public function register(): void`
`60`	`54`
`61`	`55`	`$this->app->alias(TracerInterface::class, 'opentelemetry.tracer');`
`62`	`56`
`63`		`- Log::debug('OpenTelemetry: Service provider registered successfully');`
	`57`	`+ Log::debug('[laravel-open-telemetry] Service provider registered successfully');`
`64`	`58`	`}`
`65`	`59`
`66`	`60`	`/**`
`@@ -126,7 +120,7 @@ protected function registerMiddlewares(): void`
`126`	`120`	`// Enable TraceId middleware globally by default`
`127`	`121`	`if (config('otel.middleware.trace_id.global', true)) {`
`128`	`122`	`$kernel->pushMiddleware(AddTraceId::class);`
`129`		`- Log::debug('OpenTelemetry: Middleware registered globally for automatic tracing');`
	`123`	`+ Log::debug('[laravel-open-telemetry] Middleware registered globally for automatic tracing');`
`130`	`124`	`}`
`131`	`125`	`}`
`132`	`126`	`}`