OpenTelemetry API 的性能和阻塞
本文档定义了有助于设计人员创建安全易用的 OpenTelemetry 客户端的通用原则。
核心原则
以下是核心原则
- 默认情况下，库不应阻塞最终用户应用程序。
- 库不应消耗无界内存资源。
尽管实现监控存在不可避免的开销，但 API 应尽可能不降低最终用户应用程序的性能。因此，它不应阻塞最终用户应用程序，也不应消耗过多内存资源。
如果实现支持并发，请参阅 并发和线程安全。
非阻塞与内存消耗之间的权衡
不完整的异步 I/O 任务或后台任务可能会消耗内存来保留其状态。在这种情况下，存在用于丢弃一些任务以防止内存耗尽与保留所有任务以防止信息丢失之间的权衡。
如果 OpenTelemetry 客户端存在这种权衡，它应向最终用户提供以下选项
- 防止信息丢失：保留所有信息，但可能消耗大量资源
- 防止阻塞：在负载过重时丢弃部分信息，并显示警告日志以告知信息何时开始丢失以及何时恢复
- 应提供更改丢弃阈值的选项
- 最好提供一个指标来表示有效的采样率
- OpenTelemetry 客户端可能为日志记录提供此选项
最终用户应用程序应了解日志的大小
如果最终用户应用程序发出过多日志，默认情况下日志记录可能会消耗大量内存。此默认行为旨在保留日志而不是丢弃它。为了使资源使用有界，最终用户应考虑减少传递给导出器的日志量。
因此，OpenTelemetry 客户端应提供一种过滤日志以供 OpenTelemetry 捕获的方法。最终用户应用程序可能想将大量日志记录到日志文件或 stdout（或其他地方），但不想将所有日志发送到 OpenTelemetry 导出器。
在 OpenTelemetry 客户端的文档中，指出默认情况下过多的日志会消耗大量资源，然后指导如何过滤日志，这是一个好主意。
关机和显式刷新可能会阻塞
OpenTelemetry 客户端在关机时可能会阻塞最终用户应用程序。关机时，它必须刷新数据以防止信息丢失。OpenTelemetry 客户端应支持用户可配置的超时，以防在关机时发生阻塞。
如果 OpenTelemetry 客户端支持显式刷新操作，它也可能发生阻塞。但应支持可配置的超时。
文档
如果特定语言的实现具有本文档中未描述的特殊特性，则应记录这些特性。