数据库链路追踪深度实践：如何为SQL Server和Entity Framework Core启用opentelemetry-dotnet-contrib遥测

数据库链路追踪深度实践如何为SQL Server和Entity Framework Core启用opentelemetry-dotnet-contrib遥测【免费下载链接】opentelemetry-dotnet-contribThis repository contains set of components extending functionality of the OpenTelemetry .NET SDK. Instrumentation libraries, exporters, and other components can find their home here.项目地址: https://gitcode.com/gh_mirrors/op/opentelemetry-dotnet-contribopentelemetry-dotnet-contrib是 OpenTelemetry .NET SDK 的官方扩展仓库提供了一系列开箱即用的 instrumentation 库和 exporter。本文手把手教你为SQL ServerSqlClient和Entity Framework Core启用数据库链路追踪几分钟内就能看到完整的数据库调用链与性能指标帮你快速定位慢查询。为什么数据库追踪值得优先接入数据库往往是后端应用性能的重灾区。启用数据库链路追踪后你可以看到每一条 SQL 的执行耗时快速锁定慢查询关联上下游调用HTTP 请求 → 服务 → 数据库形成完整链路获得标准化指标如db.client.operation.duration数据库操作耗时直方图⚠️自动标记错误异常时 span 会带上error.type属性便于告警本仓库中两个核心组件组件状态适用场景OpenTelemetry.Instrumentation.SqlClientStable稳定版直接使用Microsoft.Data.SqlClient/System.Data.SqlClientOpenTelemetry.Instrumentation.EntityFrameworkCoreBeta预发布使用 EF Core 访问关系型数据库一键启用 SqlClient 数据库链路追踪第一步安装 NuGet 包dotnet add package OpenTelemetry.Instrumentation.SqlClient第二步在应用启动时注册using var tracerProvider Sdk.CreateTracerProviderBuilder() .AddSqlClientInstrumentation() .AddConsoleExporter() // 实际项目中替换为 OTLP 等导出器 .Build();仅两行核心代码所有通过 SqlClient 执行的数据库操作就会被自动追踪。完整的官方说明见 README.md。你会采集到哪些数据每个数据库 span 都会自动携带语义约定v1.44属性属性含义db.system.name数据库系统如microsoft.sql_serverdb.namespace数据库名称db.operation.name操作类型如SELECTdb.query.summary已脱敏的 SQL 查询摘要server.address/server.port数据库服务器地址与端口error.type出错时的异常类型同时还会暴露指标db.client.operation.duration单位秒用于在监控面板中观察数据库操作耗时分布。 源码中指标定义可见 SqlTelemetryHelper.cs其中预设了 0.001s 到 10s 的分桶边界天然适合数据库场景。进阶配置过滤、增强与实验特性通过SqlClientTraceInstrumentationOptions可精细控制行为选项定义见 SqlClientTraceInstrumentationOptions.cs只追踪特定命令Filter例如只采集存储过程调用减少噪音.AddSqlClientInstrumentation(opt opt.Filter cmd cmd is SqlCommand c c.CommandType CommandType.StoredProcedure)增强 spanEnrichWithSqlCommand可拿到原始SqlCommand对象补充自定义标签如命令超时时间CommandTimeout。记录异常事件RecordException设为true后SqlException会作为 Activity Event 记录在 span 上默认关闭仅 .NET 运行时支持。三个实验特性环境变量开启环境变量作用OTEL_DOTNET_EXPERIMENTAL_SQLCLIENT_ENABLE_TRACE_DB_QUERY_PARAMETERS输出db.query.parameter.key参数属性 ⚠️ 参数可能含敏感数据谨慎开启OTEL_DOTNET_EXPERIMENTAL_SQLCLIENT_ENABLE_RECORD_RETURNED_ROWS记录db.response.returned_rows返回行数OTEL_DOTNET_EXPERIMENTAL_SQLCLIENT_ENABLE_TRACE_CONTEXT_PROPAGATION将 traceparent 写入数据库CONTEXT_INFO实现服务端追踪⚠️ 注意Microsoft.Data.SqlClientv3.x 版本存在已知问题instrumentation 不生效v4.0 已修复请升级到 4.0。为 Entity Framework Core 启用追踪如果你的应用通过 EF Core 访问数据库可以叠加 EF Core instrumentation 获得 ORM 层的视图当前支持 SQL Server、PostgreSQL 等关系型数据库不支持 Cosmos DB 等 NoSQL。安装与注册dotnet add package --prerelease OpenTelemetry.Instrumentation.EntityFrameworkCoreservices.AddOpenTelemetry() .WithTracing(builder builder .AddEntityFrameworkCoreInstrumentation() .AddConsoleExporter());在 ASP.NET Core 中通常放在ConfigureServices里即可。详细文档见 README.md。同样支持 Filter 与增强.AddEntityFrameworkCoreInstrumentation(options { options.Filter (providerName, command) command.CommandType CommandType.StoredProcedure; // 仅存储过程 })选项定义见 EntityFrameworkInstrumentationOptions.cs。 EF Core 与 SqlClient instrumentation 可以同时启用EF Core 层提供 ORM 视角SqlClient 层提供更底层的 SQL 细节两者互不冲突。避坑指南新手最容易踩的 4 个坑Activity.Duration不含读取结果集的时间ExecuteReader()场景下span 时长只统计到请求成功为止遍历DataReader的时间不算在内。若发现span 很快但页面很慢大概率时间花在数据枚举上。Microsoft.Data.SqlClientv3.不兼容* 升级到 v4.0否则 instrumentation 静默失效。Filter、EnrichWithSqlCommand、RecordException仅 .NET 运行时可用.NET Framework 下这些选项不存在需要依赖Filter之外的其他方式控制。EF Core 组件是 Beta 版本基于实验性语义约定未来版本可能有破坏性变更生产使用请留意 CHANGELOG.md。常见问题FAQQspan 里的 SQL 语句会被完整记录吗A不会。查询文本经过脱敏处理db.query.summary字面量值会被替换避免数据泄露。脱敏逻辑见 SqlProcessor.cs。Q如何把数据导出到监控平台A把AddConsoleExporter()替换为你使用的 exporter如 OTLP、GenAI/Geneva 等本仓库也提供了 Exporter.Geneva 等官方扩展。Q如何查看测试用例学习用法A参考 OpenTelemetry.Instrumentation.SqlClient.Tests 与 OpenTelemetry.Instrumentation.EntityFrameworkCore.Tests其中覆盖了各种 SQL 场景下的追踪行为。总结步骤操作1dotnet add package安装对应 instrumentation 包2启动时调用AddSqlClientInstrumentation()/AddEntityFrameworkCoreInstrumentation()3按需配置Filter、Enrich与实验特性4接入 exporter在 Grafana 等平台查看链路只需极少量代码你就能获得标准化的数据库链路追踪与指标。建议先用控制台导出器本地验证 span 结构再接入生产监控栈平滑完成从猜慢查询到看链路的升级 【免费下载链接】opentelemetry-dotnet-contribThis repository contains set of components extending functionality of the OpenTelemetry .NET SDK. Instrumentation libraries, exporters, and other components can find their home here.项目地址: https://gitcode.com/gh_mirrors/op/opentelemetry-dotnet-contrib创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考