dotnet/extensions 项目中的日志采样器命名变更解析

背景介绍

在dotnet/extensions项目中，开发团队最近对日志采样器的API命名进行了重要调整。这一变更源于最初设计的ProbabilisticSampler命名可能与OpenTelemetry .NET API产生冲突。经过深入讨论和技术评估，团队决定将相关API统一更名为RandomProbabilisticSampler。

技术细节

变更内容

此次命名变更涉及多个类和方法的调整：

1. 扩展方法重命名：

   • 原AddProbabilisticSampler方法更名为AddRandomProbabilisticSampler
   • 保持了原有的三种重载形式：配置参数、配置委托和直接参数设置

2. 选项类重命名：

   • 原ProbabilisticSamplerOptions类更名为RandomProbabilisticSamplerOptions
   • 内部集合属性类型也相应变更

3. 过滤规则类重命名：

   • 原ProbabilisticSamplerFilterRule类更名为RandomProbabilisticSamplerFilterRule
   • 构造函数签名同步更新

使用示例

变更后的API使用方式如下：

loggingBuilder.AddRandomProbabilisticSampler(0.1, LogLevel.Information);

设计考量

开发团队在命名决策过程中考虑了多个备选方案：

1. 完全移除Probabilistic：如使用RandomSampler，但被认为过于通用，不能充分表达API功能
2. 其他描述性词汇：如"Stochastic"、"Linear"、"Uniform"等
3. 组合命名：最终选择的"RandomProbabilistic"方案

这一决策主要基于以下技术因素：

• 与OpenTelemetry规范中的术语区分（特别是"Consistent Probability Sampling"概念）
• 保持API名称的准确性和自描述性
• 避免与现有生态系统的命名冲突

技术影响

此次变更属于纯粹的API表面调整，不会影响实际功能实现。由于这些API是全新引入的，不会对现有代码产生兼容性问题。对于开发者而言，主要需要关注的是：

1. 新项目应直接使用新命名
2. 文档和示例需要相应更新
3. 团队内部代码评审时需注意命名规范

总结

dotnet/extensions项目通过这次细致的API命名调整，展现了其对生态系统兼容性和API设计严谨性的重视。这种前瞻性的命名策略有助于：

• 避免未来与OpenTelemetry等关键组件的潜在冲突
• 提供更准确的API语义表达
• 为后续功能扩展奠定良好的基础

开发者在实现日志采样功能时，应采用新的RandomProbabilisticSampler系列API，以确保长期兼容性和最佳实践。