Skip to content
Skills Library
Programming · Building & coding

sentry

/sentry

Use when adding error tracking, performance monitoring or release health to .NET apps — builder.WebHost.UseSentry, SetBeforeSend, SentrySdk.CaptureException, TracesSampleRate, StartTransaction/StartChild spans, Source Context, symbol upload. Also for events not arriving because Dsn is empty (the SDK stays silent), tracing producing no transactions, PII leaking into events, and StartChildSpan no longer existing in 6.x. Sentry .NET SDK.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
13
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when adding error tracking, performance monitoring or release health to .NET apps — builder.WebHost.UseSentry, SetBeforeSend, SentrySdk.CaptureException, TracesSampleRate, StartTransaction/StartChild spans, Source Context, symbol upload. Also for events not arriving because Dsn is empty (the SDK stays silent), tracing producing no transactions, PII leaking into events, and StartChildSpan no longer existing in 6.x. Sentry .NET SDK.

Original author description

Use when adding error tracking, performance monitoring or release health to .NET apps — builder.WebHost.UseSentry, SetBeforeSend, SentrySdk.CaptureException, TracesSampleRate, StartTransaction/StartChild spans, Source Context, symbol upload. Also for events not arriving because Dsn is empty (the SDK stays silent), tracing producing no transactions, PII leaking into events, and StartChildSpan no longer existing in 6.x. Sentry .NET SDK.

How it works

  1. 概述
  2. 环境准备
  3. 核心 API
  4. 典型工作流
  5. 最佳实践
  6. 常见问题
  7. AI 使用建议
  8. 相关技能
  9. 参考资源
Original SKILL.md headings · 275 lines, 750 words
SKILL.md preview
---
name: sentry
description: "Use when adding error tracking, performance monitoring or release health to .NET apps — builder.WebHost.UseSentry, SetBeforeSend, SentrySdk.CaptureException, TracesSampleRate, StartTransaction/StartChild spans, Source Context, symbol upload. Also for events not arriving because Dsn is empty (the SDK stays silent), tracing producing no transactions, PII leaking into events, and StartChildSpan no longer existing in 6.x. Sentry .NET SDK."
tags:
  - dotnet
  - csharp
  - error-tracking
  - monitoring
  - performance
  - aspnet-core
  - observability
---

> **项目地址:** <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

```bash
# 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

```xml
<ItemGroup>
  <PackageReference Include="Sentry.AspNetCore" Version="6.12.1" />
</ItemGroup>
```

#### 方式三:包管理器控制台

```powershell
Install-Package Sentry.AspNetCore -Version 6.12.1
```

#### 验证安装

```bash
dotnet list package | grep -i sentry
```

### 初始化

```csharp
// 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

### 手动上报异常

```csharp
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);
}
```

### 性能追踪

```csharp
// 创建 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 自动采集

```csharp
// ASP.NET Core 自动记录:
// - HTTP 请求/响应
// - EF Core 查询
// - 日志消息(需配置 SentryLogs)
// - 认证事件

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

---

## 典型工作流

### ASP.NET Core 完整集成

```csharp
// 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)

```bash
# 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`(默认)

---

## 常见问题

| 问题 | 解决方案 |
|------|---------|
| 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 使用建议

### 推荐工作流

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](../furion/SKILL.md)
- **sqlsugar** — .NET ORM:[../sqlsugar/SKILL.md](../sqlsugar/SKILL.md)
- **dotnet-reactor** — .NET 代码保护:[../dotnet-reactor/SKILL.md](../dotnet-reactor/SKILL.md)

---

## 参考资源

- [Sentry .NET 文档](https://docs.sentry.io/platforms/dotnet/)
- [Sentry ASP.NET Core 指南](https://docs.sentry.io/platforms/dotnet/guides/aspnetcore/)
- [sentry-dotnet GitHub](https://github.com/getsentry/sentry-dotnet)
- [Sentry 自托管文档](https://develop.sentry.dev/self-hosted/)
- 自托管架构组件:事件上报先经 Relay(接收/过滤/采样/限流/脱敏网关),查询侧由 Snuba(基于 ClickHouse)提供事件搜索与聚合
- [性能监控文档](https://docs.sentry.io/product/performance/)

Versions

RepositoryScoreLicence
This page · znlgis/opengis-skills100MIT
sgtlaugh/skills100MIT
cardstack/boxel100MIT
TerminalSkills/skills100Apache-2.0
tech-leads-club/agent-skills100MIT
foryourhealth111-pixel/Vibe-Skills100Apache-2.0
getsentry/junior100Apache-2.0
greedychipmunk/agent-skills100MIT
G1Joshi/Agent-Skills100MIT

Database snapshot: 13.11.2026 · package version 68ad0cbac0a0 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95sentry-sdk-setup
    Set up Sentry in any language or framework. Detects the user's platform and loads the right SDK skill. Use when asked to add Sentry, install an SDK, or set up error monitoring in a project.
  • 100sentry-error-capture
    Implement advanced error capture and context enrichment with Sentry. Use when adding captureException/captureMessage calls, enriching errors with user context, tags, breadcrumbs, or custom fingerprinting. Trigger with "sentry error capture", "sentry context", "enrich sentry…
  • 100sentry-go-sdk
    Full Sentry SDK setup for Go. Use when asked to "add Sentry to Go", "install sentry-go", "setup Sentry in Go", or configure error monitoring, tracing, logging, metrics, or crons for Go applications. Supports net/http, Gin, Echo, Fiber, FastHTTP, Iris, Negroni, and gRPC.
  • 90sentry-dotnet-sdk
    Full Sentry SDK setup for .NET. Use when asked to "add Sentry to .NET", "install Sentry for C#", or configure error monitoring, tracing, profiling, logging, or crons for ASP.NET Core, MAUI, WPF, WinForms, Blazor, Azure Functions, or any other .NET application.
  • 100sentry-install-auth
    Install and configure Sentry SDK authentication with DSN setup. Use when setting up Sentry error tracking, configuring DSN, or initializing Sentry in a Node.js or Python project. Trigger with "install sentry", "setup sentry", "sentry auth", "configure sentry DSN".
  • 100sentry-nextjs
    Sentry for Next.js 15 — SDK installation (client/server/edge configs), source maps upload, performance tracing, session replay, error boundary integration, instrumenting Server Actions and Route Handlers, alert rules, environments (dev/staging/prod), release tracking, user…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.