故障排除

来自 OpenTelemetry .NET 仓库（opentelemetry-dotnet 和 opentelemetry-dotnet-contrib）的所有组件都使用 EventSource 进行内部日志记录。OpenTelemetry SDK 使用的 EventSource 名称是“OpenTelemetry-Sdk”。要了解其他组件使用的 EventSource 名称，请参阅各个组件的文档。

虽然可以使用 PerfView 或 dotnet-trace 等工具查看这些日志，但 SDK 还附带了自助诊断功能，有助于排查问题。

自助诊断

OpenTelemetry SDK 附带内置的自助诊断功能。启用后，此功能会监听由所有 OpenTelemetry 组件（即名称以“OpenTelemetry-”开头的 EventSources）生成的内部日志，并将它们写入日志文件。

可以在进程运行时（无需重启进程）启用、更改或禁用自助诊断功能。SDK 会以非独占的只读模式每 10 秒尝试读取一次配置文件。SDK 会根据配置创建或覆盖一个带有新日志的文件。此文件不会超过配置的最大大小，并以循环方式覆盖。

要启用自助诊断，请进入进程的 当前工作目录，创建一个名为 OTEL_DIAGNOSTICS.json 的配置文件，内容如下：

{
  "LogDirectory": ".",
  "FileSize": 32768,
  "LogLevel": "Warning",
  "FormatMessage": "true"
}

要禁用自助诊断，请删除配置文件。

配置参数

配置文件支持以下参数：

LogDirectory

存储输出日志文件的目录。可以是绝对路径，也可以是相对于当前目录的相对路径。

FileSize

一个正整数，指定日志文件的大小（以 KiB 为单位）。此值必须在 [1024, 131072]（1 MiB <= 大小 <= 128 MiB）范围内，否则将被调整到最近的上限或下限。日志文件永远不会超过此配置的大小，并以循环方式覆盖。

LogLevel

要捕获的事件的最低级别。它必须是 EventLevel 枚举 的 值 之一。级别表示事件的严重性。较低的严重性级别包含较高的严重性级别。例如，Warning 包含 Error 和 Critical 级别。

FormatMessage

一个布尔值，用于控制是否通过将占位符（{0}, {1} 等）替换为其实际参数值来格式化日志消息。当设置为 false（默认）时，消息会以未格式化的占位符和原始参数值进行记录。当设置为 true 时，占位符会被替换为格式化后的参数值，以提高可读性。

示例（FormatMessage: false，默认）

2025-07-24T01:45:04.1020880Z:Measurements from Instrument '{0}', Meter '{1}' will be ignored. Reason: '{2}'. Suggested action: '{3}'{dotnet.gc.collections}{System.Runtime}{Instrument belongs to a Meter not subscribed by the provider.}{Use AddMeter to add the Meter to the provider.}

示例（FormatMessage: true）

2025-07-24T01:44:44.7059260Z:Measurements from Instrument 'dotnet.gc.collections', Meter 'System.Runtime' will be ignored. Reason: 'Instrument belongs to a Meter not subscribed by the provider.'. Suggested action: 'Use AddMeter to add the Meter to the provider.'

备注

在指定的 LogDirectory 中会生成一个名为 ExecutableName.ProcessId.log（例如，myapp.exe.12345.log）的日志文件，日志将写入其中。

如果 SDK 无法解析 LogDirectory、FileSize 或 LogLevel 字段，则配置文件将被视为无效，不会生成日志文件。

当 LogDirectory 或 FileSize 更改时，SDK 会根据新配置创建或覆盖一个带有新日志的文件。配置文件的大小不能超过 4 KiB。如果文件大于 4 KiB，则只读取前 4 KiB 的内容。

日志文件可能不是标准的文本文件格式，目的是为了实现最小开销和有限的资源使用：如果日志文本小于配置的大小，可能会有结尾的 NUL 字符；一旦写入操作到达末尾，就会从头开始覆盖现有文本。