bitzorcas
中 EN

Concept

可观测性

OpenTelemetry 可观测性 — 通过 OTLP 导出的 traces + metrics、自定义 SqlSugar ActivitySource、CorrelationId 传播和结构化日志。

Last updated

BitzOrcas 使用 OpenTelemetry 作为统一可观测性框架，通过 OTLP 导出 traces 和 metrics。API 宿主和 JobHost 共享相同的 ServiceDefaults 配置。

架构

API 宿主 / JobHost
       │
       ▼
OpenTelemetry SDK
├── Traces: ASP.NET Core + HttpClient + SqlSugar ActivitySource
└── Metrics: ASP.NET Core + HttpClient + Runtime (GC/ThreadPool/CPU)
       │
       ▼
OTLP Exporter → Collector (OTLP 端点)
                       │
                       ▼
              Jaeger / Tempo / Datadog 等

ServiceDefaults

两个宿主共享 BitzOrcas.ServiceDefaults.AddServiceDefaults()：

builder.Services.AddOpenTelemetry()
    .ConfigureResource(resource => resource
        .AddService(serviceName, serviceVersion)
        .AddAttributes(new[] { new("deployment.environment", environment) }))
    .WithTracing(tracing => tracing
        .AddAspNetCoreInstrumentation()     // HTTP 入站
        .AddHttpClientInstrumentation()      // HTTP 出站
        .AddSource(BitzOrcasActivitySources.All) // SqlSugar 自定义
        .AddOtlpExporter(o => o.Endpoint = endpoint))
    .WithMetrics(metrics => metrics
        .AddAspNetCoreInstrumentation()
        .AddHttpClientInstrumentation()
        .AddRuntimeInstrumentation()         // GC / ThreadPool / CPU
        .AddOtlpExporter(o => o.Endpoint = endpoint));

资源属性

属性来源描述
service.name程序集名或 OTEL_SERVICE_NAME”BitzOrcas.Api” 或 “BitzOrcas.JobHost”
service.version程序集版本”1.0.0”
deployment.environmentOTEL_DEPLOYMENT_ENVIRONMENT”development” / “staging” / “production”

OTLP 端点配置

{
  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
  "OTEL_SERVICE_NAME": "bitzorcas-api",
  "OTEL_DEPLOYMENT_ENVIRONMENT": "development"
}

生产端点由编排系统（Aspire/K8s）注入。

自定义 ActivitySource

SqlSugar 操作通过 BitzOrcasActivitySources 发出自定义 span：

public static class BitzOrcasActivitySources
{
    public static string[] All => [SqlSugar];
}

这为数据库操作提供查询级跟踪，无需修改 SqlSugar 内部。

CorrelationId 传播

CorrelationIdMiddleware 在整个请求链中生成/传播 X-Correlation-Id 头：

  • 缺少头：生成新 UUID
  • 已有头：原样传播
  • 包含在所有 ProblemDetails 错误响应中
  • 通过 ICorrelationContext 注入可用

结构化日志

BitzOrcas 使用 ASP.NET Core 内置的 ILogger<T> 配合结构化参数：

logger.LogInformation(
    "Note created {NoteId} by {UserId} in tenant {TenantId}",
    note.Id, user.UserId, user.TenantId);

日志输出为 UTF-8 编码（Program.cs 中 Console.OutputEncoding = Encoding.UTF8），确保中文字符正确渲染。

业务上下文标签 (OTel)

租户和用户上下文作为 OTel 业务标签传播，用于仪表盘关联：

tenant.id = "100"
user.id = "abc-123"
caller.type = "User" | "Application"

采样

默认：ParentBasedSampler(AlwaysOnSampler)。生产环境可通过以下方式切换：

Terminal window
export OTEL_TRACES_SAMPLER=traceidratio
export OTEL_TRACES_SAMPLER_ARG=0.1  # 10% 采样

另见