feat(sentry): add singleton support for Logs class

[huangdijia]

Summary

• Add \Sentry\Logs\Logs::getInstance to SingletonAspect whitelist to ensure proper coroutine isolation
• Move Logs::getInstance()->flush() and TraceMetrics::getInstance()->flush() outside the $client null check for proper cleanup
• Ensures Logs singleton instances are properly isolated per coroutine context

Changes

SingletonAspect.php

• Added \Sentry\Logs\Logs::class to the singleton whitelist in both the method patterns and match expression

Integration.php

• Moved Logs::getInstance()->flush() and TraceMetrics::getInstance()->flush() outside the $client !== null conditional block
• This ensures these singletons are always flushed properly, regardless of client state

Test plan

• Verify Logs singleton is properly isolated across coroutines
• Ensure flush is called even when client is null

🤖 Generated with Claude Code

Summary by CodeRabbit

发布说明

• Bug 修复

  • 改进了事件刷新机制，确保日志和指标收集更加可靠。

• 优化

  • 优化了内部资源管理机制，提升系统稳定性。

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

该PR在单例注册表中添加了Sentry\Logs\Logs::class以启用其懒加载实例化，并修改了flushEvents()方法使日志和指标刷新调用总是执行，而不依赖客户端存在。

Changes

组件 / 文件	变更摘要
单例注册机制 src/sentry/src/Aspect/SingletonAspect.php	在公共$classes数组中注册Sentry\Logs\Logs::class . '::getInstance'，并在process()方法的动态解析映射中将其作为singleton处理，采用与IntegrationRegistry相同的Context::getOrSet机制
事件刷新逻辑 src/sentry/src/Integration.php	flushEvents()现使用nullsafe操作符执行客户端刷新逻辑，而日志和TraceMetrics刷新调用改为无条件执行，无需客户端存在

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

• fix(sentry): remove duplicate code and improve singleton instance reset in SingletonAspect #1048 — 修改SingletonAspect::process()中的singleton解析行为和闭包绑定逻辑
• refactor(sentry): optimize SingletonAspect with match expression #1049 — 调整SingletonAspect.php中的单例类处理和注册机制
• feat(sentry): improve event flushing and expand listener coverage #908 — 修改Integration::flushEvents以刷新Sentry\Logs实例，与本PR的日志刷新改动关联

Poem

🐰 日志工厂添单例，懒惰加载展身手，
刷新无虑客户端，指标数据总流走，
两处修补齐协力，系统更稳妥～

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding singleton support for the Logs class in the Sentry aspect configuration.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/sentry-logs-singleton-support

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 325304c and a7cc6ae.

📒 Files selected for processing (2)

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

🧰 Additional context used

📓 Path-based instructions (4)

**/*.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.php: All PHP files must include declare(strict_types=1) at the top
Use PSR-12 coding standards for PHP code formatting
Use 4-space indentation with short array syntax in PHP code
Use .php-cs-fixer.php configuration for PHP code formatting

All PHP files must include a strict_types declaration at the top

**/*.php: Follow project PHP coding standard enforced by php-cs-fixer with PSR-12 style, 4-space indentation, and short array syntax
Maintain type coverage by updating or adding tests when public APIs change; ensure composer test:types stays green before pushing

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

src/**/src/**/*.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use namespace pattern FriendsOfHyperf\{ComponentName} for all component classes

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

src/*/src/**/*.php

📄 CodeRabbit inference engine (CLAUDE.md)

src/*/src/**/*.php: Namespace convention for components must follow FriendsOfHyperf{ComponentName}
All code must be coroutine-safe and avoid global state without proper context management, blocking I/O operations, and non-coroutine-safe third-party libraries without wrappers
Use Hyperf's Context API for request-scoped data instead of global state
Follows PSR-12 coding standards and use PHP-CS-Fixer for automatic formatting
Use PHPStan at maximum level for static analysis
Ensure component namespace doesn't conflict with existing Hyperf components or other packages in the ecosystem
Integrate deeply with Hyperf's Dependency Injection container for service registration
Leverage Hyperf's AOP (Aspect-Oriented Programming) for cross-cutting concerns via aspects defined in ConfigProvider
Use Hyperf's Event System to register listeners for framework events in components
All code must support coroutine-based concurrency using Swoole/Swow compatibility

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

src/**/*.php

📄 CodeRabbit inference engine (AGENTS.md)

Each component lives in its own subdirectory with PSR-4 namespaces matching FriendsOfHyperf\*

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

🧠 Learnings (1)

📚 Learning: 2025-12-12T05:33:43.947Z

Learnt from: CR
Repo: friendsofhyperf/components PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-12T05:33:43.947Z
Learning: Applies to src/*/src/**/*.php : Leverage Hyperf's AOP (Aspect-Oriented Programming) for cross-cutting concerns via aspects defined in ConfigProvider

Applied to files:

• src/sentry/src/Aspect/SingletonAspect.php

🧬 Code graph analysis (2)

src/sentry/src/Aspect/SingletonAspect.php (1)

src/sentry/src/Integration.php (1)

• Integration (29-155)

src/sentry/src/Integration.php (1)

src/sentry/class_map/SentrySdk.php (2)

• SentrySdk (24-65)
• getCurrentHub (51-54)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (18)

• GitHub Check: Test on PHP 8.3 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.1 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.1 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.3 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.1 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.2 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.3 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.1 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.1 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.1 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.3 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.2 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.3 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.3 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 6.1.3

🔇 Additional comments (3)

src/sentry/src/Aspect/SingletonAspect.php (2)

25-25: 正确添加了 Logs 单例到白名单

将 \Sentry\Logs\Logs::class . '::getInstance' 添加到 $classes 数组中,使得 AOP 切面能够拦截该方法调用,这与 PR 目标一致。

---

50-51: 正确实现了 Logs 单例的协程隔离

将 \Sentry\Logs\Logs::class 添加到 match 表达式中,并使用 Context::getOrSet 确保每个协程上下文都有独立的 Logs 实例。使用 Closure::bind 模式表明 Logs 类的构造函数是私有的,这与 IntegrationRegistry 的实现模式一致。

src/sentry/src/Integration.php (1)

109-111: 改进了刷新逻辑，确保日志和指标始终被正确刷新

使用 nullsafe 操作符 ?-> 简化了客户端刷新逻辑。由于 Hyperf 中所有状态数据应该存储在 Hyperf\Context\Context 类中，get/set 操作仅限于执行它们的对应协程，并在协程结束时自动销毁相关上下文数据，SingletonAspect 通过 Context::getOrSet() 确保 Logs::getInstance() 和 TraceMetrics::getInstance() 总是返回有效实例，因此将这些调用设为无条件执行是安全的。这种方式充分利用了 Hyperf 的协程上下文管理机制，避免了传统 null 检查的开销，同时确保即使客户端为 null 时日志和指标也能被正确刷新。

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 PHPStan (2.1.33)

At least one path must be specified to analyse.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

This PR enhances Sentry integration coroutine safety by adding proper singleton isolation for the Logs class and ensuring cleanup methods are always called regardless of client state.

Key Changes:

• Added Logs singleton to the coroutine isolation whitelist in SingletonAspect
• Moved Logs and TraceMetrics flush calls outside the client null check to ensure proper cleanup in all scenarios

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/sentry/src/Aspect/SingletonAspect.php	Added Logs class to singleton whitelist in both $classes array and match expression to enable per-coroutine instance isolation
src/sentry/src/Integration.php	Moved Logs::getInstance()->flush() and TraceMetrics::getInstance()->flush() outside the client null check to ensure these singletons are always flushed, preventing data loss when client is unavailable

The changes are well-structured and follow existing patterns in the codebase. The Logs class is correctly configured using Closure::bind() for instantiation (consistent with other protected-constructor singletons like HubAdapter and IntegrationRegistry), and the flush logic improvement ensures that accumulated logs and metrics are properly cleaned up even when the Sentry client is not available.

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/sentry/src/Aspect/SingletonAspect.php (1)

43-45: 修复预存在的逻辑错误

代码中存在逻辑错误:当 $arguments[0] 不存在时(条件为真),却尝试访问 $arguments[0],这会导致未定义索引错误。正确的逻辑应该是:当参数存在时才追加到 key 中。

🔎 建议的修复

-if (! array_key_exists(0, $arguments)) {
+if (array_key_exists(0, $arguments)) {
     $key .= '#' . $arguments[0];
 }

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 325304c and a7cc6ae.

📒 Files selected for processing (2)

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

🧰 Additional context used

📓 Path-based instructions (4)

**/*.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.php: All PHP files must include declare(strict_types=1) at the top
Use PSR-12 coding standards for PHP code formatting
Use 4-space indentation with short array syntax in PHP code
Use .php-cs-fixer.php configuration for PHP code formatting

All PHP files must include a strict_types declaration at the top

**/*.php: Follow project PHP coding standard enforced by php-cs-fixer with PSR-12 style, 4-space indentation, and short array syntax
Maintain type coverage by updating or adding tests when public APIs change; ensure composer test:types stays green before pushing

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

src/**/src/**/*.php

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

Use namespace pattern FriendsOfHyperf\{ComponentName} for all component classes

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

src/*/src/**/*.php

📄 CodeRabbit inference engine (CLAUDE.md)

src/*/src/**/*.php: Namespace convention for components must follow FriendsOfHyperf{ComponentName}
All code must be coroutine-safe and avoid global state without proper context management, blocking I/O operations, and non-coroutine-safe third-party libraries without wrappers
Use Hyperf's Context API for request-scoped data instead of global state
Follows PSR-12 coding standards and use PHP-CS-Fixer for automatic formatting
Use PHPStan at maximum level for static analysis
Ensure component namespace doesn't conflict with existing Hyperf components or other packages in the ecosystem
Integrate deeply with Hyperf's Dependency Injection container for service registration
Leverage Hyperf's AOP (Aspect-Oriented Programming) for cross-cutting concerns via aspects defined in ConfigProvider
Use Hyperf's Event System to register listeners for framework events in components
All code must support coroutine-based concurrency using Swoole/Swow compatibility

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

src/**/*.php

📄 CodeRabbit inference engine (AGENTS.md)

Each component lives in its own subdirectory with PSR-4 namespaces matching FriendsOfHyperf\*

Files:

• src/sentry/src/Aspect/SingletonAspect.php
• src/sentry/src/Integration.php

🧠 Learnings (1)

📚 Learning: 2025-12-12T05:33:43.947Z

Learnt from: CR
Repo: friendsofhyperf/components PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-12T05:33:43.947Z
Learning: Applies to src/*/src/**/*.php : Leverage Hyperf's AOP (Aspect-Oriented Programming) for cross-cutting concerns via aspects defined in ConfigProvider

Applied to files:

• src/sentry/src/Aspect/SingletonAspect.php

🧬 Code graph analysis (2)

src/sentry/src/Aspect/SingletonAspect.php (1)

src/sentry/src/Integration.php (1)

• Integration (29-155)

src/sentry/src/Integration.php (1)

src/sentry/class_map/SentrySdk.php (2)

• SentrySdk (24-65)
• getCurrentHub (51-54)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (18)

• GitHub Check: Test on PHP 8.3 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.1 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.1 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.3 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.1 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.2 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.3 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.1 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.1 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.1 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.3 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.2 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.3 with Swoole 6.1.3
• GitHub Check: Test on PHP 8.3 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 6.1.3

🔇 Additional comments (3)

src/sentry/src/Aspect/SingletonAspect.php (2)

25-25: 正确添加了 Logs 单例到白名单

将 \Sentry\Logs\Logs::class . '::getInstance' 添加到 $classes 数组中,使得 AOP 切面能够拦截该方法调用,这与 PR 目标一致。

---

50-51: 正确实现了 Logs 单例的协程隔离

将 \Sentry\Logs\Logs::class 添加到 match 表达式中,并使用 Context::getOrSet 确保每个协程上下文都有独立的 Logs 实例。使用 Closure::bind 模式表明 Logs 类的构造函数是私有的,这与 IntegrationRegistry 的实现模式一致。

src/sentry/src/Integration.php (1)

109-111: 改进了刷新逻辑，确保日志和指标始终被正确刷新

使用 nullsafe 操作符 ?-> 简化了客户端刷新逻辑。由于 Hyperf 中所有状态数据应该存储在 Hyperf\Context\Context 类中，get/set 操作仅限于执行它们的对应协程，并在协程结束时自动销毁相关上下文数据，SingletonAspect 通过 Context::getOrSet() 确保 Logs::getInstance() 和 TraceMetrics::getInstance() 总是返回有效实例，因此将这些调用设为无条件执行是安全的。这种方式充分利用了 Hyperf 的协程上下文管理机制，避免了传统 null 检查的开销，同时确保即使客户端为 null 时日志和指标也能被正确刷新。