Sentry

项目地址： 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 或自托管）。

核心特性

支持的平台

环境准备

安装

方式一：dotnet CLI

bashCopy code
# 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

xmlCopy code
<ItemGroup>
  <PackageReference Include="Sentry.AspNetCore" Version="6.12.1" />
</ItemGroup>

方式三：包管理器控制台

powershellCopy code
Install-Package Sentry.AspNetCore -Version 6.12.1

验证安装

bashCopy code
dotnet list package | grep -i sentry

初始化

csharpCopy code
// 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

手动上报异常

csharpCopy code
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);
}

性能追踪

csharpCopy code
// 创建 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 自动采集

csharpCopy code
// ASP.NET Core 自动记录：
// - HTTP 请求/响应
// - EF Core 查询
// - 日志消息（需配置 SentryLogs）
// - 认证事件

// 手动添加 Breadcrumb
SentrySdk.AddBreadcrumb(
    "User clicked checkout button",
    category: "ui",
    level: BreadcrumbLevel.Info
);

典型工作流

ASP.NET Core 完整集成

csharpCopy code
// 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）

bashCopy code
# Sentry 自托管（开发环境）
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
./install.sh
# 访问 http://localhost:9000

最佳实践

1. DSN 安全：DSN 可以公开（不像 API Key），但仍建议通过环境变量管理
2. 采样率：生产环境建议 TracesSampleRate = 0.1-0.3，避免高流量下性能影响
3. Release 标记：设置 Release 标签，让 Sentry 关联代码变更与错误
4. BeforeSend 钩子：过滤敏感信息（密码、Token）再上报
5. 用户隐私：遵守 GDPR，配置 SendDefaultPii = false（默认）

常见问题

AI 使用建议

推荐工作流

1. 安装 SDK：dotnet add package Sentry.AspNetCore（ASP.NET Core）或 Sentry（基础）
2. 配置 DSN：在 appsettings.json 中设置 Sentry:Dsn 或环境变量 SENTRY_DSN
3. 启用追踪：builder.WebHost.UseSentry()（Web）或 SentrySdk.Init()（控制台），并设置 TracesSampleRate
4. 自动采集：ASP.NET Core、EF Core、HttpClient 等自动采集性能数据
5. 自定义事件：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）提供事件搜索与聚合
• 性能监控文档