日志 API
状态: 稳定
日志 API 提供给日志库作者用于构建 日志附加器，这些附加器使用此 API 在现有日志库和 OpenTelemetry 日志数据模型之间进行桥接。
日志 API 也可以直接由遥测库以及被遥测的库或应用程序调用。
日志 API 由以下主要组件组成
- LoggerProvider 是 API 的入口点。它提供对
Logger的访问。 - Logger 负责将日志作为 LogRecord 发出。
graph TD
A[LoggerProvider] -->|Get| B(Logger)
B -->|Emit| C(LogRecord)LoggerProvider
Logger 可以通过 LoggerProvider 访问。
通常，LoggerProvider 期望从一个中心位置访问。因此，API 应该提供一种设置/注册和访问全局默认 LoggerProvider 的方法。
LoggerProvider 操作
LoggerProvider 必须提供以下函数
- 获取
Logger
获取 Logger
此 API 必须接受以下 遥测范围 参数
name：指定 遥测范围 的名称，例如 遥测库（例如io.opentelemetry.contrib.mongodb）、包、模块或类名。如果应用程序或库内置了 OpenTelemetry 遥测，则 被遥测库 和 遥测库 可以指向同一个库。在这种情况下，name指的是该库或应用程序中的模块名称或组件名称。对于定义了日志名称的日志源（例如 Java Logger Name），日志名称应记录为遥测范围名称。version（可选）：指定遥测范围的版本（如果该范围有版本）（例如，库版本）。示例值：1.0.0。schema_url（可选）：指定应记录在发出的遥测中的 Schema URL。attributes（可选）：指定要与发出的遥测关联的遥测范围属性。此 API 必须支持接受可变数量的属性，包括零个。
术语“相同”应用于 Logger 时，表示所有参数都相等。术语“不同”应用于 Logger 时，表示至少有一个参数的值不同。
Logger
Logger 负责发出 LogRecord。
Logger 必须提供一个函数来
Logger 应提供函数来
发出 LogRecord
调用此 API 的效果是将 LogRecord 发送到处理管道。
API 必须接受以下参数
- 时间戳（可选）
- 观察到的时间戳（可选）
- 与
LogRecord关联的 上下文。当支持隐式上下文时，此参数应为可选，如果未指定，则必须使用当前上下文。当仅支持显式上下文时，此参数应为必需。 - 严重性编号（可选）
- 严重性文本（可选）
- 正文（可选）
- 属性（可选）
- 事件名称（可选）
Enabled
为了帮助用户避免在生成 LogRecord 时执行计算成本高昂的操作，Logger 应提供此 Enabled API。
API 应接受以下参数
此 API 必须返回一种符合语言习惯的布尔类型。返回值 true 表示 Logger 对提供的参数已启用，返回值 false 表示 Logger 对提供的参数已禁用。
返回值并非始终是静态的，它会随时间而变化。API 应记录，遥测作者需要每次 发出 LogRecord 时都调用此 API，以确保获得最新的响应。
可选和必填参数
定义的这些操作包含各种参数，其中一些被标记为可选。未标记为可选的参数是必需的。
对于每个可选参数，API 必须支持接受它，但不得强制用户提供它。
对于每个必需参数，API 必须支持强制用户提供它。
并发要求
对于支持并发执行的语言，日志 API 提供了特定的保证和安全性。
LoggerProvider - 所有方法都可以安全地并发调用。
Logger - 所有方法都可以安全地并发调用。