ApplicationInsights-dotnet 自诊断完全指南ApplicationInsightsDiagnostics.json 排障实战【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnetApplicationInsights-dotnet 是微软 Azure 应用性能监控APM的官方 .NET SDK。当遥测数据丢失、上报异常或采样行为不符合预期时内置的**自诊断Self-Diagnostics**功能可以把 SDK 内部事件写入本地日志文件。本文围绕ApplicationInsightsDiagnostics.json配置文件讲解如何 3 步开启自诊断、读懂日志文件命名规则并给出一份常见问题排查清单。为什么需要 ApplicationInsights 自诊断在 .NET SDK 3.x 中自诊断是一个SDK 自己记录自己日志的轻量机制捕获内部事件SDK 通过 .NET EventSource 发出内部事件如通道发送失败、配置解析警告自诊断会监听所有Microsoft-ApplicationInsights-*与OpenTelemetry-*前缀的事件源一并写入日志文件。零侵入不需要修改任何代码只需在进程目录下放一个 JSON 配置文件。⚡热更新SDK 每 10 秒重新读取一次配置运行中可随时开启、调整或关闭。 注意3.x 的自诊断日志写入本地文件不再集成到 Visual Studio 输出窗口。快速开启自诊断的 3 个步骤第 1 步确定配置文件放置位置SDK 按以下顺序查找ApplicationInsightsDiagnostics.json见 SelfDiagnosticsConfigParser.cs环境变量APPLICATIONINSIGHTS_LOG_DIAGNOSTICS指定的目录最高优先级进程的当前工作目录应用程序基目录AppContext.BaseDirectoryWindows 上可以用 Sysinternals Process Explorer 双击进程在 Image 选项卡查看 Current directory确认第 2 个查找位置。第 2 步创建配置文件在应用根目录与 exe/dll 同目录最稳妥新建ApplicationInsightsDiagnostics.json内容如下{ LogDirectory: ., FileSize: 1024, LogLevel: Warning }⚠️ 配置文件必须不超过4 KiB否则只会读取前 4 KiB 内容。第 3 步启动应用应用启动后日志会在LogDirectory指定的目录中自动生成。若使用 .NET SDK 风格项目可参考示例工程的做法让配置文件随构建复制到输出目录见 AspNetCoreWebApp.csproj示例配置见 ApplicationInsightsDiagnostics.json。配置参数详解LogDirectory、FileSize、LogLevel 怎么用参数类型说明LogDirectory字符串日志输出目录绝对路径或相对当前目录的路径如.表示当前目录FileSize正整数日志文件大小单位KiB取值范围 1024 ~ 131072即 1 MiB ~ 128 MiB越界会被自动取整到最近的边界值LogLevel字符串最低捕获级别Verbose/Information/Warning/Error/Critical两个容易踩坑的细节级别是向下包含的设置Warning会同时记录Error和Critical事件想只看错误选Error即可。任一字段解析失败 整个配置失效缺少某个字段、数值不合法或 JSON 格式错误自诊断会直接关闭不会产生任何日志——这也是文件没生成的最常见原因。日志文件在哪里命名规则一文看懂日志文件以内存映射文件Memory Mapped File方式写入实现见 MemoryMappedFileHandler.cs命名格式固定为年-月-日-时-分-秒.可执行文件名.进程ID.log例如20250821-150314.MyApp.dll.12345.log时间戳为文件创建时的 UTC 时间。环形覆盖写日志写到文件末尾后从头覆盖文件永远不会超过FileSize配置的大小。 每次重新创建日志时文件第一行是Successfully opened file.可用来确认文件刚被创建。 日志行格式为UTC时间戳:事件消息{参数1}{参数2}UTF-8 编码可直接用文本编辑器打开排查。免重启热更新10 秒自动生效的配置刷新机制SelfDiagnosticsConfigRefresher.cs 中的后台工作线程每 10 秒以非独占只读方式重新读取配置文件✏️修改日志级别、换目录、调文件大小直接编辑 JSON 文件最多 10 秒后自动生效目录或大小变化会重建日志文件。关闭自诊断直接删除配置文件即可10 秒内日志写入停止。⏱ 因此排障时不用担心重启应用才能生效线上服务也可以安全地临时打开诊断、收集日志后再删除。排障实战4 个常见问题排查清单现象可能原因解决方法完全没有日志文件生成配置文件放在了 SDK 查找不到的目录把 JSON 复制到进程当前工作目录或应用基目录或用环境变量指定目录配置文件存在但无日志JSON 缺字段 / 拼写错误 / 超过 4 KiB对照上文参数表逐字段检查保持三个字段齐全且格式合法日志内容太少找不到错误LogLevel设得太高如Critical临时改为Warning或Information10 秒后自动生效日志乱序或开头内容残缺环形覆盖写把旧日志覆盖了属于正常行为如需更长的保留时间把FileSize调大上限 131072进阶技巧在容器或托管环境中无法控制进程工作目录时设置环境变量APPLICATIONINSIGHTS_LOG_DIAGNOSTICS指向一个目录需将配置文件放入该目录日志也会输出到该目录此时文件内的LogDirectory字段会被忽略。源码与文档导航想深入了解实现细节可以从以下文件入手 官方自诊断文档troubleshooting/Readme.md 配置解析逻辑BASE/src/Microsoft.ApplicationInsights/Extensibility/Implementation/Tracing/SelfDiagnosticsConfigParser.cs 10 秒刷新机制BASE/src/Microsoft.ApplicationInsights/Extensibility/Implementation/Tracing/SelfDiagnosticsConfigRefresher.cs 事件监听与日志编码BASE/src/Microsoft.ApplicationInsights/Extensibility/Implementation/Tracing/SelfDiagnosticsEventListener.cs 单元测试可作为行为依据BASE/Test/Microsoft.ApplicationInsights.Test/Microsoft.ApplicationInsights.Tests/Extensibility/Implementation/Tracing/SelfDiagnostics/总结ApplicationInsights-dotnet 自诊断的核心就一句话在进程目录下放一个包含LogDirectory、FileSize、LogLevel三个字段的ApplicationInsightsDiagnostics.jsonSDK 就会把内部日志环形写入本地文件且 10 秒内热更新生效。遇到遥测异常时先把级别调到Warning打开诊断读几分钟日志再删除文件通常就能快速定位问题所在。【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ApplicationInsights-dotnet 自诊断完全指南：ApplicationInsightsDiagnostics.json 排障实战
ApplicationInsights-dotnet 自诊断完全指南ApplicationInsightsDiagnostics.json 排障实战【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnetApplicationInsights-dotnet 是微软 Azure 应用性能监控APM的官方 .NET SDK。当遥测数据丢失、上报异常或采样行为不符合预期时内置的**自诊断Self-Diagnostics**功能可以把 SDK 内部事件写入本地日志文件。本文围绕ApplicationInsightsDiagnostics.json配置文件讲解如何 3 步开启自诊断、读懂日志文件命名规则并给出一份常见问题排查清单。为什么需要 ApplicationInsights 自诊断在 .NET SDK 3.x 中自诊断是一个SDK 自己记录自己日志的轻量机制捕获内部事件SDK 通过 .NET EventSource 发出内部事件如通道发送失败、配置解析警告自诊断会监听所有Microsoft-ApplicationInsights-*与OpenTelemetry-*前缀的事件源一并写入日志文件。零侵入不需要修改任何代码只需在进程目录下放一个 JSON 配置文件。⚡热更新SDK 每 10 秒重新读取一次配置运行中可随时开启、调整或关闭。 注意3.x 的自诊断日志写入本地文件不再集成到 Visual Studio 输出窗口。快速开启自诊断的 3 个步骤第 1 步确定配置文件放置位置SDK 按以下顺序查找ApplicationInsightsDiagnostics.json见 SelfDiagnosticsConfigParser.cs环境变量APPLICATIONINSIGHTS_LOG_DIAGNOSTICS指定的目录最高优先级进程的当前工作目录应用程序基目录AppContext.BaseDirectoryWindows 上可以用 Sysinternals Process Explorer 双击进程在 Image 选项卡查看 Current directory确认第 2 个查找位置。第 2 步创建配置文件在应用根目录与 exe/dll 同目录最稳妥新建ApplicationInsightsDiagnostics.json内容如下{ LogDirectory: ., FileSize: 1024, LogLevel: Warning }⚠️ 配置文件必须不超过4 KiB否则只会读取前 4 KiB 内容。第 3 步启动应用应用启动后日志会在LogDirectory指定的目录中自动生成。若使用 .NET SDK 风格项目可参考示例工程的做法让配置文件随构建复制到输出目录见 AspNetCoreWebApp.csproj示例配置见 ApplicationInsightsDiagnostics.json。配置参数详解LogDirectory、FileSize、LogLevel 怎么用参数类型说明LogDirectory字符串日志输出目录绝对路径或相对当前目录的路径如.表示当前目录FileSize正整数日志文件大小单位KiB取值范围 1024 ~ 131072即 1 MiB ~ 128 MiB越界会被自动取整到最近的边界值LogLevel字符串最低捕获级别Verbose/Information/Warning/Error/Critical两个容易踩坑的细节级别是向下包含的设置Warning会同时记录Error和Critical事件想只看错误选Error即可。任一字段解析失败 整个配置失效缺少某个字段、数值不合法或 JSON 格式错误自诊断会直接关闭不会产生任何日志——这也是文件没生成的最常见原因。日志文件在哪里命名规则一文看懂日志文件以内存映射文件Memory Mapped File方式写入实现见 MemoryMappedFileHandler.cs命名格式固定为年-月-日-时-分-秒.可执行文件名.进程ID.log例如20250821-150314.MyApp.dll.12345.log时间戳为文件创建时的 UTC 时间。环形覆盖写日志写到文件末尾后从头覆盖文件永远不会超过FileSize配置的大小。 每次重新创建日志时文件第一行是Successfully opened file.可用来确认文件刚被创建。 日志行格式为UTC时间戳:事件消息{参数1}{参数2}UTF-8 编码可直接用文本编辑器打开排查。免重启热更新10 秒自动生效的配置刷新机制SelfDiagnosticsConfigRefresher.cs 中的后台工作线程每 10 秒以非独占只读方式重新读取配置文件✏️修改日志级别、换目录、调文件大小直接编辑 JSON 文件最多 10 秒后自动生效目录或大小变化会重建日志文件。关闭自诊断直接删除配置文件即可10 秒内日志写入停止。⏱ 因此排障时不用担心重启应用才能生效线上服务也可以安全地临时打开诊断、收集日志后再删除。排障实战4 个常见问题排查清单现象可能原因解决方法完全没有日志文件生成配置文件放在了 SDK 查找不到的目录把 JSON 复制到进程当前工作目录或应用基目录或用环境变量指定目录配置文件存在但无日志JSON 缺字段 / 拼写错误 / 超过 4 KiB对照上文参数表逐字段检查保持三个字段齐全且格式合法日志内容太少找不到错误LogLevel设得太高如Critical临时改为Warning或Information10 秒后自动生效日志乱序或开头内容残缺环形覆盖写把旧日志覆盖了属于正常行为如需更长的保留时间把FileSize调大上限 131072进阶技巧在容器或托管环境中无法控制进程工作目录时设置环境变量APPLICATIONINSIGHTS_LOG_DIAGNOSTICS指向一个目录需将配置文件放入该目录日志也会输出到该目录此时文件内的LogDirectory字段会被忽略。源码与文档导航想深入了解实现细节可以从以下文件入手 官方自诊断文档troubleshooting/Readme.md 配置解析逻辑BASE/src/Microsoft.ApplicationInsights/Extensibility/Implementation/Tracing/SelfDiagnosticsConfigParser.cs 10 秒刷新机制BASE/src/Microsoft.ApplicationInsights/Extensibility/Implementation/Tracing/SelfDiagnosticsConfigRefresher.cs 事件监听与日志编码BASE/src/Microsoft.ApplicationInsights/Extensibility/Implementation/Tracing/SelfDiagnosticsEventListener.cs 单元测试可作为行为依据BASE/Test/Microsoft.ApplicationInsights.Test/Microsoft.ApplicationInsights.Tests/Extensibility/Implementation/Tracing/SelfDiagnostics/总结ApplicationInsights-dotnet 自诊断的核心就一句话在进程目录下放一个包含LogDirectory、FileSize、LogLevel三个字段的ApplicationInsightsDiagnostics.jsonSDK 就会把内部日志环形写入本地文件且 10 秒内热更新生效。遇到遥测异常时先把级别调到Warning打开诊断读几分钟日志再删除文件通常就能快速定位问题所在。【免费下载链接】ApplicationInsights-dotnetApplicationInsights-dotnet项目地址: https://gitcode.com/gh_mirrors/ap/ApplicationInsights-dotnet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考