GraphQL-dotnet 项目中使用 OpenTelemetry 实现监控的完整指南

概述

在现代微服务架构中，监控和可观测性变得至关重要。本文将详细介绍如何在 GraphQL-dotnet 项目中集成 OpenTelemetry 来实现完整的监控解决方案，包括常见的配置问题和解决方案。

OpenTelemetry 基础配置

在 .NET 8.0 环境中，基本的 OpenTelemetry 配置通常包括以下组件：

services.AddOpenTelemetry()
    .ConfigureResource(resource => resource.AddService("API"))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddSqlClientInstrumentation()
        .AddConsoleExporter());

这个配置会收集：

• ASP.NET Core 请求的跟踪信息
• HTTP 客户端调用的跟踪信息
• SQL 数据库访问的跟踪信息
• 并将结果输出到控制台

GraphQL 监控的特殊配置

许多开发者在配置完基础监控后，发现 GraphQL 相关的操作没有被监控到。这是因为 GraphQL-dotnet 使用了自己的 ActivitySource，需要显式添加到 OpenTelemetry 配置中：

services.AddOpenTelemetry()
    // 其他配置保持不变
    .WithTracing(tracing => tracing
        // 原有配置
        .AddSource(GraphQLTelemetryProvider.SourceName) // 关键配置
        // 其他配置
    );

完整的 GraphQL 服务配置

一个完整的 GraphQL 服务配置应该包含以下内容：

services.AddSingleton<IGraphQLExceptionHandler, ExceptionHandler>();
services.AddGraphQL(builder => builder
    .AddSchema<MySchema>()
    .ConfigureExecutionOptions(options =>
    {
        var requestServices = options.RequestServices ?? throw new Exception("Missing RequestServices");
        var handler = requestServices.GetRequiredService<IGraphQLExceptionHandler>();
        options.UnhandledExceptionDelegate = ctx => handler.HandleException(ctx);
    })
    .AddSystemTextJson()
    .AddDataLoader()
    .AddGraphTypes(typeof(MySchema).Assembly)
    .UseTelemetry() // 启用 GraphQL 遥测
);

常见问题排查

1. 看不到 GraphQL 跟踪信息：

   • 确保已调用 .UseTelemetry()
   • 检查是否添加了 AddSource(GraphQLTelemetryProvider.SourceName)

2. 跟踪信息不完整：

   • 检查 Activity.Current 是否为 null
   • 验证 DisplayName、IsAllDataRequested 和 ActivityTraceFlags 属性

3. 性能考虑：

   • 在生产环境中，考虑使用更高效的导出器（如 Jaeger 或 Zipkin）替代控制台导出器
   • 适当配置采样率以避免性能开销

最佳实践

1. 资源命名：为服务设置明确的名称（如示例中的"API"），便于在分布式系统中识别

2. 异常处理：如示例所示，实现自定义的 IGraphQLExceptionHandler 可以统一处理异常

3. 环境区分：根据运行环境（开发/生产）配置不同的导出器和采样策略

4. 监控指标：除了跟踪，还可以考虑添加指标监控，全面掌握系统状态

通过以上配置和最佳实践，开发者可以在 GraphQL-dotnet 项目中实现全面的监控解决方案，为系统运维和问题排查提供有力支持。