ASP.NET 中如何使用Exceptionless分布式日志收集框架

# ASP.NET 中如何使用Exceptionless分布式日志收集框架

## 目录
1. [什么是Exceptionless](#什么是exceptionless)
2. [Exceptionless核心功能](#exceptionless核心功能)
3. [环境准备](#环境准备)
4. [ASP.NET Core集成Exceptionless](#aspnet-core集成exceptionless)
   - [4.1 安装NuGet包](#41-安装nuget包)
   - [4.2 基础配置](#42-基础配置)
   - [4.3 高级配置](#43-高级配置)
5. [日志记录实践](#日志记录实践)
   - [5.1 基本日志记录](#51-基本日志记录)
   - [5.2 异常捕获](#52-异常捕获)
   - [5.3 自定义事件](#53-自定义事件)
6. [仪表板使用指南](#仪表板使用指南)
7. [性能优化建议](#性能优化建议)
8. [常见问题解答](#常见问题解答)
9. [总结](#总结)

## 什么是Exceptionless

Exceptionless是一个开源的分布式日志收集框架，专门为.NET应用程序设计。它提供实时错误报告、日志收集和应用监控功能，具有以下特点：

- 支持结构化日志记录
- 提供强大的搜索和过滤功能
- 支持事件富化（添加额外上下文）
- 具备实时通知能力
- 提供直观的仪表板

与ELK等日志系统相比，Exceptionless更专注于.NET生态，提供了更精细的错误分析和更简单的集成方式。

## Exceptionless核心功能

1. **错误跟踪**：自动捕获未处理异常
2. **日志收集**：支持多级日志（Debug, Info, Warning, Error）
3. **事件富化**：自动收集请求头、环境变量等上下文信息
4. **实时通知**：支持邮件、Slack等通知渠道
5. **趋势分析**：识别错误发生频率和模式

## 环境准备

### 部署选项
1. **SaaS服务**：直接使用官方托管服务（免费版有限制）
2. **自托管**：通过Docker或IIS部署（推荐生产环境使用）

```bash
# 使用Docker快速启动自托管服务
docker run -d -p 5000:80 -p 5001:443 exceptionless/exceptionless:latest

ASP.NET Core要求

• .NET Core 3.1+
• 推荐使用最新LTS版本

ASP.NET Core集成Exceptionless

4.1 安装NuGet包

dotnet add package Exceptionless.AspNetCore
dotnet add package Exceptionless

4.2 基础配置

在Program.cs中添加服务注册：

builder.Services.AddExceptionless(builder.Configuration["Exceptionless:ApiKey"]);

在appsettings.json中添加配置：

{
  "Exceptionless": {
    "ApiKey": "YOUR_API_KEY_HERE",
    "ServerUrl": "http://localhost:5000" // 自托管地址
  }
}

4.3 高级配置

// 自定义配置
ExceptionlessClient.Default.Configuration
    .SetDefaultMinLogLevel(LogLevel.Information)
    .UseInMemoryStorage()
    .UseReferenceIds();

// 添加自定义标签
ExceptionlessClient.Default.CreateLog("AppStart").AddTags("Startup").Submit();

日志记录实践

5.1 基本日志记录

// 控制器中使用
public class HomeController : Controller
{
    private readonly ILogger<HomeController> _logger;

    public HomeController(ILogger<HomeController> logger)
    {
        _logger = logger;
    }

    public IActionResult Index()
    {
        _logger.LogInformation("Home page visited at {Time}", DateTime.UtcNow);
        return View();
    }
}

5.2 异常捕获

自动捕获未处理异常：

// 在Program.cs中
app.UseExceptionless();

// 手动捕获
try {
    // 可能出错的代码
} catch (Exception ex) {
    ex.ToExceptionless().Submit();
}

5.3 自定义事件

// 创建自定义事件
var eventBuilder = ExceptionlessClient.Default.CreateLog("CustomEvent")
    .SetMessage("用户执行了关键操作")
    .SetProperty("UserId", user.Id)
    .SetGeo(latitude, longitude);

// 添加标签和上下文
eventBuilder.AddTags("Security", "Audit")
    .AddObject(context.HttpContext.Request);

// 提交事件
eventBuilder.Submit();

仪表板使用指南

1. 事件查看：按时间、类型、标签过滤
2. 错误分析：查看堆栈跟踪和上下文数据
3. 趋势图表：分析错误频率变化
4. 通知规则：配置阈值告警

性能优化建议

1. 批量提交：启用UseInMemoryStorage()后自动批量处理
2. 日志级别控制：生产环境避免记录Debug日志
3. 上下文精简：只收集必要信息
4. 异步提交：默认已启用，无需额外配置

// 性能优化配置示例
ExceptionlessClient.Default.Configuration
    .UseInMemoryStorage()
    .SetBatchSize(50)
    .SetBatchInterval(TimeSpan.FromSeconds(15));

常见问题解答

Q：如何过滤敏感信息？

ExceptionlessClient.Default.Configuration.AddDataExclusion(
    "Password", "CreditCard" // 排除包含这些字段的数据
);

Q：本地开发时如何禁用？

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionless();
}

Q：如何自定义错误分组？

ex.ToExceptionless()
    .SetUserIdentity(userId)
    .SetUserDescription(email, comment)
    .Submit();

总结

Exceptionless为ASP.NET Core应用提供了强大的日志收集和错误跟踪能力。通过本文介绍，您应该能够：

1. 完成基础集成和配置
2. 记录不同级别的日志信息
3. 有效利用仪表板分析问题
4. 优化日志收集性能

对于企业级应用，建议使用自托管方案并结合APM工具进行全方位监控。

延伸阅读： - Exceptionless官方文档 - ASP.NET Core日志最佳实践 - 分布式日志系统比较 “`

注：实际使用时需要： 1. 替换YOUR_API_KEY_HERE为真实API Key 2. 更新自托管地址（如使用） 3. 补充实际的仪表板截图URL 4. 根据实际.NET版本调整代码示例