OpenTelemetry JS SDK 中为已结束的 Span 操作添加调试日志

在 OpenTelemetry JS SDK 的 sdk-trace-base 模块中，当开发者尝试对已经结束的 Span 执行修改操作时，系统会记录一个警告日志。然而，由于缺乏堆栈跟踪信息，定位这些无效操作的具体来源变得相当困难。

问题背景

根据 OpenTelemetry 规范的要求，API 在遇到无效操作时不应抛出异常，而是通过日志记录来通知开发者。当前实现中，当对已结束的 Span 执行无效操作时，系统会记录一个警告级别的日志，但这条日志不包含堆栈跟踪信息，使得调试变得困难。

解决方案

为了解决这个问题，开发团队决定在现有警告日志的基础上，增加一个调试级别的日志记录，该日志将包含完整的堆栈跟踪信息。这样开发者可以通过调整日志级别来获取更详细的调试信息。

实现细节

1. 在现有的警告日志后立即添加一个调试级别的日志
2. 调试日志包含完整的调用堆栈信息
3. 修改警告日志的提示信息，告知开发者可以通过调整日志级别获取堆栈跟踪
4. 确保该功能在 Node.js 和浏览器环境中都能正常工作

技术考量

实现时需要注意以下几点：

• 跨平台兼容性：解决方案必须在 Node.js 和浏览器环境中都能正常工作
• 性能影响：调试日志只在调试级别启用时才会记录，不会影响生产环境性能
• 日志清晰度：警告日志需要明确提示开发者如何获取更多调试信息

测试验证

新增的测试用例需要验证：

1. 当对已结束的 Span 执行操作时，是否记录了警告日志
2. 是否同时记录了包含堆栈跟踪的调试日志
3. 警告日志中是否包含获取更多调试信息的提示
4. 上述功能在 Node.js 和浏览器环境中的表现一致性

总结

这项改进显著提升了开发者在处理 Span 生命周期问题时的调试体验。通过简单的日志级别调整，开发者现在可以轻松获取导致问题的完整调用堆栈，大大缩短了定位和修复问题的时间。这是 OpenTelemetry JS SDK 持续改进开发者体验的一个典型例子。