项目地址: https://github.com/getsentry/sentry-dotnet
官方文档: https://docs.sentry.io/platforms/dotnet/
NuGet: https://www.nuget.org/packages/Sentry
最新版本: Sentry / Sentry.AspNetCore 6.12.1(截至 2026-10,NuGet 实测)
许可证: MIT
概述
Sentry 是一个开源的 错误追踪与性能监控平台,.NET SDK 支持将异常、崩溃、性能指标统一上报到 Sentry 服务端(SaaS 或自托管)。
核心特性
| 特性 | 说明 |
|---|---|
| 自动异常捕获 | 集成 ASP.NET Core / MAUI / WPF / Blazor / Console |
| 性能监控 | Transaction + Span 模型,自动采集 HTTP/DB/EF Core 耗时 |
| 源码映射 | Release + Debug Files 支持,还原压缩/混淆后的堆栈 |
| Breadcrumb | 自动记录用户操作、HTTP 请求、日志等上下文 |
| Session Replay | 用户会话回放(Web 前端支持) |
| Alerting | 基于 Issue / Metric 的告警规则 |
| 自托管 | 完整的自托管部署方案(Docker/Kubernetes) |
支持的平台
| 包名 | 用途 |
|---|---|
Sentry |
核心 SDK(控制台/Worker) |
Sentry.AspNetCore |
ASP.NET Core Web API / MVC |
Sentry.Maui |
.NET MAUI 移动应用 |
Sentry.AspNetCore.Blazor.WebAssembly |
Blazor WASM |
Sentry.EntityFramework |
Entity Framework 6 集成(EF Core 查询经内置 DiagnosticSource 自动采集) |
Sentry.DiagnosticSource |
DiagnosticSource 事件采集 |
Sentry.OpenTelemetry |
OpenTelemetry 集成 |
Sentry.Profiling |
代码级性能剖析 |
环境准备
安装
方式一:dotnet CLI
# ASP.NET Core 项目
dotnet add package Sentry.AspNetCore
# 控制台 / Worker 项目
dotnet add package Sentry
# 可选集成
dotnet add package Sentry.EntityFramework # EF6(EF Core 无需此包)
dotnet add package Sentry.DiagnosticSource # HTTP / ADO.NET 自动 Span
dotnet add package Sentry.OpenTelemetry # OTel 桥接
dotnet add package Sentry.Profiling # 性能剖析
方式二:PackageReference
<ItemGroup>
<PackageReference Include="Sentry.AspNetCore" Version="6.12.1" />
</ItemGroup>
方式三:包管理器控制台
Install-Package Sentry.AspNetCore -Version 6.12.1
验证安装
dotnet list package | grep -i sentry
初始化
// ASP.NET Core (Program.cs)
builder.WebHost.UseSentry(o =>
{
o.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
o.TracesSampleRate = 1.0; // 100% 性能追踪采样
o.Environment = builder.Environment.EnvironmentName;
o.Release = "my-app@1.0.0";
});
// 控制台应用
SentrySdk.Init(o =>
{
o.Dsn = "https://examplePublicKey@o0.ingest.sentry.io/0";
o.TracesSampleRate = 0.2; // 20% 采样
});
核心 API
手动上报异常
try
{
DoSomething();
}
catch (Exception ex)
{
// 添加额外上下文
SentrySdk.ConfigureScope(scope =>
{
scope.SetTag("feature", "payment");
scope.SetExtra("request_body", requestBody);
scope.User = new SentryUser { Id = "12345", Email = "user@example.com" };
});
SentrySdk.CaptureException(ex);
}
性能追踪
// 创建 Transaction
var transaction = SentrySdk.StartTransaction("process-order", "task");
SentrySdk.ConfigureScope(s => s.Transaction = transaction);
try
{
// Span: 数据库查询(6.12.1 的 ISpan 只有 StartChild(operation),
// 带 description 的重载是 SpanExtensions 扩展方法)
var dbSpan = transaction.StartChild("db.query", "SELECT * FROM orders");
var orders = await db.QueryAsync("SELECT * FROM orders WHERE ...");
dbSpan.Finish();
// Span: 业务逻辑
var bizSpan = transaction.StartChild("business.process");
ProcessOrders(orders);
bizSpan.Finish();
transaction.Finish(SpanStatus.Ok);
}
catch (Exception ex)
{
transaction.Finish(ex);
}
Breadcrumb 自动采集
// ASP.NET Core 自动记录:
// - HTTP 请求/响应
// - EF Core 查询
// - 日志消息(需配置 SentryLogs)
// - 认证事件
// 手动添加 Breadcrumb
SentrySdk.AddBreadcrumb(
"User clicked checkout button",
category: "ui",
level: BreadcrumbLevel.Info
);
典型工作流
ASP.NET Core 完整集成
// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.WebHost.UseSentry(o =>
{
o.Dsn = Environment.GetEnvironmentVariable("SENTRY_DSN");
o.TracesSampleRate = 0.3;
o.ProfilesSampleRate = 0.1; // 采样率
o.Environment = builder.Environment.EnvironmentName;
o.Release = $"my-api@{Assembly.GetExecutingAssembly().GetName().Version}";
// 性能:只追踪特定路由
o.TracePropagationTargets = new[] { "https://my-api.com" };
});
// EF Core 查询 Span 由 SDK 内置 DiagnosticSource 集成自动采集;
// EF6 才需要额外安装 Sentry.EntityFramework
var app = builder.Build();
// 新版 SDK 中 ASP.NET Core 请求 Transaction 自动创建(TracesSampleRate > 0 即生效),
// 无需再手动调用 UseSentryTracing()
app.MapControllers();
app.Run();
自托管部署(Docker)
# Sentry 自托管(开发环境)
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
./install.sh
# 访问 http://localhost:9000
最佳实践
- DSN 安全:DSN 可以公开(不像 API Key),但仍建议通过环境变量管理
- 采样率:生产环境建议
TracesSampleRate = 0.1-0.3,避免高流量下性能影响 - Release 标记:设置
Release标签,让 Sentry 关联代码变更与错误 - BeforeSend 钩子:过滤敏感信息(密码、Token)再上报
- 用户隐私:遵守 GDPR,配置
SendDefaultPii = false(默认)
常见问题
| 问题 | 解决方案 |
|---|---|
| DSN 在哪里获取? | Sentry Dashboard → Settings → Projects → Client Keys |
| 如何过滤敏感数据? | 使用 BeforeSend 回调或 BeforeSendTransaction |
| ASP.NET Core 中性能追踪不生效? | 确保 TracesSampleRate > 0(新版 SDK 自动创建请求 Transaction,无需额外中间件) |
| 如何与 OpenTelemetry 共存? | 安装 Sentry.OpenTelemetry,通过 OTel 桥接 |
| EF Core 查询没有追踪? | 确认 ADO.NET/DiagnosticSource 集成未被禁用;Sentry.EntityFramework 仅用于 EF6 |
AI 使用建议
推荐工作流
- 安装 SDK:
dotnet add package Sentry.AspNetCore(ASP.NET Core)或Sentry(基础) - 配置 DSN:在
appsettings.json中设置Sentry:Dsn或环境变量SENTRY_DSN - 启用追踪:
builder.WebHost.UseSentry()(Web)或SentrySdk.Init()(控制台),并设置TracesSampleRate - 自动采集:ASP.NET Core、EF Core、HttpClient 等自动采集性能数据
- 自定义事件:
SentrySdk.CaptureMessage()或SentrySdk.CaptureException()
关键注意事项
- DSN 必填:无 DSN 时 SDK 静默不工作,不会抛异常
- 性能追踪:设置
TracesSampleRate > 0才会生成 Transaction/Span;新版 SDK 自动插桩,旧文档中的UseSentryTracing()中间件已无需调用 - 采样率:生产环境建议
TracesSampleRate = 0.1(10%),避免过多数据 - 隐私过滤:用
BeforeSend回调过滤敏感数据(PII、密码等) - 自托管:Docker 部署需配置
SENTRY_SECRET_KEY和邮件服务
相关技能
- furion — .NET Web 框架:../furion/SKILL.md
- sqlsugar — .NET ORM:../sqlsugar/SKILL.md
- dotnet-reactor — .NET 代码保护:../dotnet-reactor/SKILL.md
参考资源
- Sentry .NET 文档
- Sentry ASP.NET Core 指南
- sentry-dotnet GitHub
- Sentry 自托管文档
- 自托管架构组件:事件上报先经 Relay(接收/过滤/采样/限流/脱敏网关),查询侧由 Snuba(基于 ClickHouse)提供事件搜索与聚合
- 性能监控文档