feat: add feature flag support for tracing aspects

[huangdijia]

Summary

This PR adds feature flag support to tracing aspects, enabling fine-grained control over which types of operations are traced. Each aspect now checks the corresponding feature flag before performing tracing operations.

Changes

• DbConnectionAspect: Added Feature dependency injection and check for db tracing feature flag before caching server information
• RedisConnectionAspect: Added Feature dependency injection and check for redis tracing feature flag before caching slot/node information
• ElasticsearchRequestAspect: Added Feature dependency injection and check for elasticsearch tracing feature flag before processing requests
• RpcEndpointAspect: Added Feature dependency injection and check for rpc tracing feature flag before storing server address

Benefits

• Users can now selectively enable/disable tracing for specific operation types (db, redis, elasticsearch, rpc)
• Reduces overhead when certain types of tracing are not needed
• Provides more flexible configuration options without code changes
• Consistent feature flag pattern across all tracing aspects

Test Plan

• Verify db tracing can be disabled via feature flag
• Verify redis tracing can be disabled via feature flag
• Verify elasticsearch tracing can be disabled via feature flag
• Verify rpc tracing can be disabled via feature flag
• Verify all aspects work normally when feature flags are enabled

Summary by CodeRabbit

发布说明

• 改进
  • 为数据库、Elasticsearch、Redis 和 RPC 等追踪功能添加了运行时功能门控机制。用户现可通过功能标志灵活控制各类追踪的启用和禁用状态，提供更细粒度的追踪管理能力。

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

[coderabbitai]

概述

针对四个追踪方面类（DbConnection、Elasticsearch、Redis、RpcEndpoint）进行了一致的重构，通过构造函数促进添加 Feature 依赖注入，并在各自的 process 方法中增加运行时特性开关检查，以实现对数据库、Elasticsearch、Redis 和 RPC 追踪的条件启用/禁用。

变更

方面 / 文件	变更摘要
追踪方面特性开关集成 src/sentry/src/Tracing/Aspect/DbConnectionAspect.php，src/sentry/src/Tracing/Aspect/ElasticsearchRequestAspect.php，src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php，src/sentry/src/Tracing/Aspect/RpcEndpointAspect.php	四个方面类均新增 Feature 依赖注入，通过构造函数促进（protected Feature $feature）添加为类属性；新增导入 FriendsOfHyperf\Sentry\Feature；各自的 process 方法中添加运行时守卫，检查对应追踪类型（'db'、'elasticsearch'、'redis'、'rpc'）是否启用，禁用时提前返回，跳过后续追踪逻辑。

代码审查工作量估算

🎯 2 (简单) | ⏱️ ~10 分钟

需要重点关注的区域：

• 验证所有四个方面类的构造函数签名改变是否与容器注入机制相兼容
• 确认 Feature 依赖的导入路径在所有文件中一致
• 检查运行时特性开关字符串（'db'、'elasticsearch'、'redis'、'rpc'）与 Feature 类定义中的常数对应关系
• 验证提前返回逻辑不会导致追踪上下文泄露或不完整

相关 PR

• refactor(sentry): replace Switcher class with Feature class #923：两个 PR 均对追踪方面类进行修改，注入并使用新的 FriendsOfHyperf\Sentry\Feature 依赖，替换之前的 Switcher 使用方式
• feat: add server address tracing for database connections #1024：当前 PR 更新 DbConnectionAspect 以接受 Feature 依赖并添加运行时特性开关，该 PR 则添加了初始的 DbConnectionAspect 和相关数据库追踪常数注册
• feat(sentry): add view rendering tracing support #935：当前 PR 向 DB/Elasticsearch/Redis/RPC 方面类注入 Feature 并添加运行时守卫，该 PR 则添加 ViewRenderAspect 并使用相同的 Feature 特性开关机制进行集成

建议审阅人

• guandeng
• xuanyanwow

诗歌

🐰 四个方面齐步走，特性开关把门守，
运行时刻判生死，追踪进退在心头，
注入依赖促构造，代码优雅又自由！

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.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	标题清楚地总结了这个拉取请求的主要变更——为追踪方面添加功能标志支持，与所有四个修改的文件及其实现的运行时网关逻辑完全相关。

✨ 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/add-feature-flag-support-for-tracing-aspects

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.32)

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.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php (1)

41-45: 基于 tracing span 的 Redis 开关逻辑合理，静态分析的 $result 告警可视为噪音

• 先执行 $proceedingJoinPoint->process()，再在 tap 闭包里使用 Feature::isTracingSpanEnabled('redis') 做短路，只影响上下文填充，不会改变原方法返回值，这个位置选择是安全且清晰的。
• 闭包形参 $result 当前未使用，但这是 tap 模式下很常见的写法，用于匹配回调签名。PHPMD 提示“UnusedFormalParameter”在这里属于可接受的告警，如果后续不打算在这里使用 Redis 调用结果，可以选择忽略该告警，或在静态分析配置里对这类模式放宽规则。

总体而言，这段开关逻辑实现是正确且易于维护的。

📜 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 cc3d1f5 and 5e62f2a.

📒 Files selected for processing (4)

• src/sentry/src/Tracing/Aspect/DbConnectionAspect.php (2 hunks)
• src/sentry/src/Tracing/Aspect/ElasticsearchRequestAspect.php (2 hunks)
• src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php (2 hunks)
• src/sentry/src/Tracing/Aspect/RpcEndpointAspect.php (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (4)

src/sentry/src/Tracing/Aspect/ElasticsearchRequestAspect.php (3)

src/sentry/src/Feature.php (2)

• Feature (18-75)
• isTracingSpanEnabled (39-46)

src/sentry/src/Tracing/Aspect/ElasticsearchAspect.php (2)

• __construct (56-58)
• process (60-89)

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

• feature (24-27)

src/sentry/src/Tracing/Aspect/RpcEndpointAspect.php (3)

src/sentry/src/Feature.php (2)

• Feature (18-75)
• isTracingSpanEnabled (39-46)

src/sentry/src/Tracing/Aspect/RpcAspect.php (2)

• __construct (43-47)
• process (49-60)

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

• feature (24-27)

src/sentry/src/Tracing/Aspect/DbConnectionAspect.php (5)

src/sentry/src/Feature.php (2)

• Feature (18-75)
• isTracingSpanEnabled (39-46)

src/sentry/src/Tracing/Aspect/ElasticsearchRequestAspect.php (2)

• __construct (30-32)
• process (34-66)

src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php (2)

• __construct (34-37)
• process (39-66)

src/sentry/src/Tracing/Aspect/RpcEndpointAspect.php (2)

• __construct (30-32)
• process (34-65)

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

• feature (24-27)

src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php (3)

src/sentry/src/Feature.php (2)

• Feature (18-75)
• isTracingSpanEnabled (39-46)

src/sentry/src/Tracing/Aspect/DbConnectionAspect.php (2)

• __construct (33-36)
• process (38-67)

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

• feature (24-27)

🪛 PHPMD (2.15.0)

src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php

41-41: Avoid unused parameters such as '$result'. (undefined)

(UnusedFormalParameter)

⏰ 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.1 with Swoole 6.1.2
• 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.3 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.2 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.2 with Swoole 6.1.2
• GitHub Check: Test on PHP 8.3 with Swoole 6.1.2
• 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.2 with Swoole 6.1.2
• GitHub Check: Test on PHP 8.1 with Swoole 6.1.2
• GitHub Check: Test on PHP 8.1 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.1 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.3 with Swoole 5.1.8
• GitHub Check: Test on PHP 8.3 with Swoole 6.0.2
• GitHub Check: Test on PHP 8.3 with Swoole 6.1.2

🔇 Additional comments (10)

src/sentry/src/Tracing/Aspect/RedisConnectionAspect.php (2)

15-15: 引入 Feature 依赖用于 Redis tracing 开关是合理的

这里新增对 Feature 的引用，与 DbConnectionAspect 等保持一致，有利于统一通过配置开关控制各类 tracing span，没看到问题。

---

34-37: 构造函数新增 Feature 依赖，确认是否存在手动实例化场景

通过构造函数注入 Feature 是很自然的依赖注入方式，同时仍在构造函数里初始化 WeakMap，逻辑正确。不过这会改变构造签名，如果项目中有地方手动 new RedisConnectionAspect()（而不是交给容器创建），会出现 BC 问题，建议确认一下。

src/sentry/src/Tracing/Aspect/RpcEndpointAspect.php (3)

15-15: LGTM! 导入语句正确

Feature 类的导入是必要的，且位置适当。

---

30-32: LGTM! 依赖注入实现正确

构造函数使用属性提升语法注入 Feature 依赖，与 RpcAspect 的实现模式保持一致。

---

37-39: LGTM! 特性开关逻辑正确

特性标志检查正确放置在 tap 回调内部，在获取结果之后、设置上下文之前进行判断。当 rpc 特性被禁用时，及时返回避免设置追踪上下文，同时不影响原始方法调用的结果返回。这与 RpcAspect 中的特性开关模式保持一致。

src/sentry/src/Tracing/Aspect/ElasticsearchRequestAspect.php (2)

30-32: 依赖注入实现正确。

构造函数正确地注入了 Feature 依赖，与 ElasticsearchAspect 中的模式保持一致。

---

36-38: 特性标志检查实现正确，无需修改。

验证结果显示 ElasticsearchAspect.php 也在同一行（第 62-64 行）执行了相同的特性标志检查。两个 Aspect 都遵循一致的模式：检查 isTracingSpanEnabled('elasticsearch') 标志，若禁用则提前返回。这确保了当 ElasticsearchAspect.php 在第 75 行调用 Context::get(Constants::TRACE_ELASTICSEARCH_REQUEST_DATA, []) 时，特性必然已启用，且 ElasticsearchRequestAspect 已设置了上下文数据。默认空数组提供了额外的防御性保护。

src/sentry/src/Tracing/Aspect/DbConnectionAspect.php (3)

15-15: 导入语句正确。

添加 Feature 类的导入以支持构造函数依赖注入。

---

33-36: 依赖注入实现正确。

通过构造函数提升属性注入 Feature 依赖，与其他追踪切面（RedisConnectionAspect、RpcEndpointAspect、ElasticsearchRequestAspect）的模式保持一致。WeakMap 初始化保持不变。

---

41-43: 功能开关检查实现正确，位置合理。

在 tap 回调内部检查功能开关是正确的设计：

• 数据库操作始终执行（第 40 行），不受追踪开关影响
• 功能开关仅控制是否收集追踪元数据（缓存和上下文设置）
• 与 RedisConnectionAspect 和 RpcEndpointAspect 的模式保持一致

当功能禁用时，跳过服务器信息缓存（第 45-54 行）和上下文设置（第 56-65 行），有效减少追踪开销。