企业官网建设流程全解析

Aspire 组件遥测名称全览：日志类别、Activity Source 与指标名权威清单

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire

本指南是 Aspire 开源仓库中 src/Components/Telemetry.md 的深度展开，系统整理每个 Aspire 组件暴露的日志类别（Log categories）、Activity Source 名称与指标（Metric）名称，供你在配置 OpenTelemetry、编写日志筛选规则、定制监控面板时直接检索引用。读完本文，你将掌握每个组件的遥测标识符全集，理解这些名称在组件源码中如何被注册与消费，并能据此在 Aspire Dashboard 或自有监控体系中准确过滤、聚合与告警。

为什么需要一份"遥测名称总览"

Aspire 组件的定位是"开箱即用的可观测性"：绝大多数集成在注册服务的同时，会自动接通 OpenTelemetry 的 tracing 与 metrics 管道，并透传底层客户端库的日志。但不同底层库的命名风格差异极大——Azure SDK 系遵循Azure.*命名，EF Core 系遵循Microsoft.EntityFrameworkCore.*，而 Kafka、Redis、RabbitMQ 则各有各的约定。要正确配置AddSource、AddMeter或日志筛选规则，前提就是知道确切的字符串。这份清单正是该仓库的官方答案，其内容与各组件源码中的实际注册代码一一对应（本文后续会用具体文件佐证）。

在深入清单前，先理解 Aspire 组件统一的可观测性开关。以 Npgsql 组件为例，AspirePostgreSqlNpgsqlExtensions.cs 中的注册逻辑是：

if (!settings.DisableTracing) { builder.Services.AddOpenTelemetry() .WithTracing(tracerProviderBuilder => { tracerProviderBuilder.AddNpgsql(); }); } if (!settings.DisableMetrics) { builder.Services.AddOpenTelemetry() .WithMetrics(NpgsqlCommon.AddNpgsqlMetrics); }

即每个组件都通过DisableTracing、DisableMetrics（以及DisableHealthChecks）三个布尔设置控制遥测与健康检查的启停，可在appsettings.json的组件配置节中覆盖，例如：

{ "Aspire": { "Npgsql": { "DisableTracing": false, "DisableMetrics": false } } }

这些设置项同样会写入各组件生成的 ConfigurationSchema.json 中，供 IDE 智能提示与 schema 校验使用。整体可观测性架构可进一步参考 docs/open-telemetry-architecture.md。

清单阅读约定

• Log categories：组件或底层客户端库写入ILogger的类别名称。在 Serilog、NLog 或Logging:LogLevel配置中可直接按此名称设置级别，例如"Npgsql.Command": "Debug"。
• Activity source names：tracing（分布式追踪）数据源的名称，对应 OpenTelemetry 的ActivitySource。配置TracerProviderBuilder.AddSource("...")时使用。
• Metric names：OpenTelemetry metrics 的名称，对应Meter与Instrument。配置MeterProviderBuilder.AddMeter("...")后，即可在面板上按这些名称绘图。
• 标记为none或注明"currently not supported"的项，表示该底层库当前未提供对应能力，组件因此不注册相关管道，不是文档遗漏。
• 标有 "Everything fromXxx" 的组件，表示继承其基础组件的全部遥测，仅额外追加自身新增项。

Azure SDK 系组件

Azure SDK 系组件大多复用Azure.Core与Azure.Identity的日志与追踪基础设施，Activity Source 遵循Azure.<Service>.*通配模式（通配符*表示该服务下所有相关数据源均被覆盖）。

使用要点：

• Azure.Core与Azure.Identity是 Azure SDK 的公共日志通道，几乎所有 Azure 组件都会透传这两类日志，可用于统一观察认证（Identity）与 HTTP 管线（Core）行为。
• Activity Source 中的*是通配约定而非字面名称：例如Azure.Messaging.ServiceBus.*覆盖发送方、接收方、处理器等多个 Activity Source，配置AddSource("Azure.Messaging.ServiceBus.*")即可全部捕获。OpenAI 组件同时以OpenAI.*作为 Activity Source 与 Metric 名称（Aspire.OpenAI 组件无日志类别，但同样上报OpenAI.*指标）。
• AzureAppConfiguration 组件比较特殊：它唯一的日志类别是...AzureAppConfiguration.Refresh，专门暴露配置刷新事件，便于排查"配置为什么没有热更新"。

数据库与 ORM 组件

数据库组件的遥测分两层：连接器层（Npgsql、MySqlConnector、SqlClient）提供底层追踪与连接池指标；EF Core 层提供查询、变更追踪等日志类别。EF Core 系组件共享一套几乎固定的日志类别集合，仅在 Activity Source 上透传各自底层驱动。

Npgsql（PostgreSQL）

• Log categories：Npgsql.Command、Npgsql.Connection、Npgsql.Copy、Npgsql.Exception、Npgsql.Replication、Npgsql.Transaction
• Activity source names：Npgsql
• Metric names（NpgsqlMeter 下）：
  • db.client.commands.bytes_read
  • db.client.commands.bytes_written
  • db.client.commands.duration
  • db.client.commands.executing
  • db.client.commands.failed
  • db.client.connections.create_time
  • db.client.connections.max
  • db.client.connections.pending_requests
  • db.client.connections.timeouts
  • db.client.connections.usage

Aspire.Azure.Npgsql与Aspire.Azure.Npgsql.EntityFrameworkCore.PostgreSQL两个 Azure 托管组件不新增任何遥测，完整继承上表（原文档明确标注 "Everything fromAspire.Npgsql" / "Everything fromAspire.Npgsql.EntityFrameworkCore.PostgreSQL"）。

MySqlConnector（MySQL）

• Log categories：MySqlConnector.ConnectionPool、MySqlConnector.MySqlBulkCopy、MySqlConnector.MySqlCommand、MySqlConnector.MySqlConnection、MySqlConnector.MySqlDataSource
• Activity source names：MySqlConnector
• Metric names（MySqlConnectorMeter 下）：db.client.connections.create_time、db.client.connections.use_time、db.client.connections.wait_time、db.client.connections.idle.max、db.client.connections.idle.min、db.client.connections.max、db.client.connections.pending_requests、db.client.connections.timeouts、db.client.connections.usage

MySqlConnector 的连接池指标最丰富（9 个），覆盖创建时间、使用时间、等待时间、空闲上下限、最大连接数、挂起请求、超时与利用率，是观察连接池健康度的直接依据。源码中通过 AspireMySqlConnectorExtensions.cs 的AddMeter("MySqlConnector")注册。

SqlClient 与 SQL Server

Aspire.Microsoft.Data.SqlClient组件：

• Log categories：none（客户端未提供与 logger factory 方便集成的途径）
• Activity source names：OpenTelemetry.Instrumentation.SqlClient
• Metric names：none

Aspire.Microsoft.EntityFrameworkCore.SqlServer组件：

• Log categories：Microsoft.EntityFrameworkCore.ChangeTracking、Microsoft.EntityFrameworkCore.Database.Command、Microsoft.EntityFrameworkCore.Database.Connection、Microsoft.EntityFrameworkCore.Database.Transaction、Microsoft.EntityFrameworkCore.Infrastructure、Microsoft.EntityFrameworkCore.Migrations、Microsoft.EntityFrameworkCore.Model、Microsoft.EntityFrameworkCore.Model.Validation、Microsoft.EntityFrameworkCore.Query、Microsoft.EntityFrameworkCore.Update
• Activity source names：OpenTelemetry.Instrumentation.SqlClient
• Metric names：none

注意 EF Core 的 SqlServer 组件在 tracing 上同样复用OpenTelemetry.Instrumentation.SqlClient（见 AspireSqlServerEFCoreSqlClientExtensions.cs 中tracerProviderBuilder.AddSqlClientInstrumentation()），其Migrations日志类别可专门用于观测迁移执行。

Pomelo.EntityFrameworkCore.MySql 与 Oracle.EntityFrameworkCore

Pomelo（EF Core + MySQL）组件：

• Log categories：与 EF Core SqlServer 组件相同的 10 个Microsoft.EntityFrameworkCore.*类别（ChangeTracking、Database.Command、Database.Connection、Database.Transaction、Infrastructure、Migrations、Model、Model.Validation、Query、Update）
• Activity source names：MySqlConnector
• Metric names：与Aspire.MySqlConnector相同的 9 个db.client.connections.*指标

Oracle.EntityFrameworkCore 组件：

• Log categories：与 EF Core SqlServer 组件相同的 10 个Microsoft.EntityFrameworkCore.*类别
• Activity source names：Oracle.ManagedDataAccess.Core
• Metric names：none

MongoDB 与 EF Core Cosmos

Aspire.MongoDB.Driver组件（日志类别细分到 MongoDB 内部子系统）：

• Log categories：MongoDB、MongoDB.Command、MongoDB.SDAM、MongoDB.ServerSelection、MongoDB.Connection、MongoDB.Internal
• Activity source names：MongoDB.Driver.Core.Extensions.DiagnosticSources
• Metric names：none

源码中该 Activity Source 名称被定义为常量ActivityNameSource = "MongoDB.Driver.Core.Extensions.DiagnosticSources"（见 AspireMongoDBDriverExtensions.cs），并在 csproj 中引入MongoDB.Driver.Core.Extensions.DiagnosticSources与OpenTelemetry.Extensions.Hosting包（Aspire.MongoDB.Driver.csproj）。

Aspire.MongoDB.EntityFrameworkCore组件额外追加 EF Core 层日志类别：Microsoft.EntityFrameworkCore.ChangeTracking、Microsoft.EntityFrameworkCore.Database.Command、Microsoft.EntityFrameworkCore.Infrastructure、Microsoft.EntityFrameworkCore.Model、Microsoft.EntityFrameworkCore.Model.Validation、Microsoft.EntityFrameworkCore.Query、Microsoft.EntityFrameworkCore.Update（无Migrations、Database.Connection、Database.Transaction），Activity Source 仍为MongoDB.Driver.Core.Extensions.DiagnosticSources。

Aspire.Microsoft.EntityFrameworkCore.Cosmos组件：

• Log categories：Azure-Cosmos-Operation-Request-Diagnostics、Microsoft.EntityFrameworkCore.ChangeTracking、Microsoft.EntityFrameworkCore.Database.Command、Microsoft.EntityFrameworkCore.Infrastructure、Microsoft.EntityFrameworkCore.Query
• Activity source names：Azure.Cosmos.Operation
• Metric names：none

消息队列与流式处理组件

Aspire.Confluent.Kafka

这是当前清单中遥测最完整的组件之一，同时提供日志、追踪与两组指标：

• Log categories：Aspire.Confluent.Kafka
• Activity source names：OpenTelemetry.Instrumentation.ConfluentKafka
• Metric names：
  • Aspire.Confluent.Kafka（组件自建 Meter）下：
    • messaging.kafka.consumer.queue.message_count
    • messaging.kafka.producer.queue.message_count
    • messaging.kafka.producer.queue.size
    • messaging.kafka.network.tx
    • messaging.kafka.network.transmitted
    • messaging.kafka.network.rx
    • messaging.kafka.network.received
    • messaging.kafka.message.tx
    • messaging.kafka.message.transmitted
    • messaging.kafka.message.rx
    • messaging.kafka.message.received
  • OpenTelemetry.Instrumentation.ConfluentKafka（透传底层插桩 Meter）下：
    • messaging.publish.duration
    • messaging.publish.messages
    • messaging.receive.duration
    • messaging.receive.messages

源码佐证：ConfluentKafkaCommon.MeterName = "Aspire.Confluent.Kafka"（ConfluentKafkaCommon.cs），metric 名称常量定义于 ConfluentKafkaMetrics.cs；生产端与消费端扩展分别通过AddMeter(ConfluentKafkaCommon.MeterName)、AddKafkaProducerInstrumentation/AddKafkaConsumerInstrumentation注册（AspireKafkaProducerExtensions.cs）。底层插桩来自仓库 vendoring 的OpenTelemetry.Instrumentation.ConfluentKafka源码（Aspire.Confluent.Kafka.csproj）。

Aspire.RabbitMQ.Client

• Log categories：RabbitMQ.Client
• Activity source names：
  • Aspire.RabbitMQ.Client（连接建立与重试尝试）
  • RabbitMQ.Client.Publisher（消息发布操作，仅 RabbitMQ.Client v7+）
  • RabbitMQ.Client.Subscriber（消息消费操作，仅 RabbitMQ.Client v7+）
• Metric names：none（RabbitMQ.Client 库当前不支持）

源码中组件自建ActivitySource(ActivitySourceName)，其中ActivitySourceName = "Aspire.RabbitMQ.Client"（AspireRabbitMQExtensions.cs），用于上报连接建立与重试链路；发布/订阅追踪则依赖 RabbitMQ.Client v7 及以上版本的 Activity Source。

Aspire.NATS.Net

• Log categories：NATS
• Activity source names：NATS.Net
• Metric names：none（NATS.Net 库当前不支持）

缓存组件

Aspire.StackExchange.Redis组件：

• Log categories：StackExchange.Redis
• Activity source names：OpenTelemetry.Instrumentation.StackExchangeRedis
• Metric names：none（StackExchange.Redis 库当前不支持）

Redis 组件的实现细节值得注意：它没有直接调用AddRedisInstrumentation()，而是手动注册 Activity Source 并延迟接入插桩，原因是AddRedisInstrumentation()会导致TelemetryHostedService在启动时通过 DI 解析并连接IConnectionMultiplexer——一旦 Redis 不可用，应用会在启动阶段崩溃。组件改用t.AddSource(StackExchangeRedisConnectionInstrumentation.ActivitySource.Name)+ConfigureRedisInstrumentation+AddInstrumentation的方式，在真正创建连接时才注册插桩（AspireRedisExtensions.cs），这解释了清单中 Activity Source 名称的由来，也是排查"Redis 未启动但应用正常启动"这一行为的源码依据。

Aspire.StackExchange.Redis.DistributedCaching与Aspire.StackExchange.Redis.OutputCaching均继承Aspire.StackExchange.Redis的全部遥测（"Everything from ... plus"），并各自追加一条日志类别：

• DistributedCaching 追加：Microsoft.Extensions.Caching.StackExchangeRedis
• OutputCaching 追加：Microsoft.AspNetCore.OutputCaching.StackExchangeRedis

其他组件

几点解读：

• Aspire.Seq 是唯一标注 N/A 的组件：它扮演 telemetry sink（把日志/追踪转储到 Seq 服务器），自身不产生遥测，因此没有 Activity Source 与 Metric；Seq日志类别主要用于输出转储过程本身的信息。
• Aspire.Microsoft.Azure.Cosmos（原生 Cosmos 客户端）与Aspire.Microsoft.EntityFrameworkCore.Cosmos（EF Core 版）共用Azure-Cosmos-Operation-Request-Diagnostics日志类别与Azure.Cosmos.OperationActivity Source，但 EF Core 版额外叠加了 EF Core 日志类别。
• Elasticsearch、Milvus、Qdrant 三个组件明确注明底层库未提供相应能力，配置时无需（也无法）为其注册对应管道。

如何利用这份清单做实战配置

1. 按组件开启追踪与指标

在 AppHost 的 Program.cs 中，为需要的组件 Source/Meter 显式注册（多数组件已自动注册，这里用于自建管道或覆盖默认行为）：

builder.Services.AddOpenTelemetry() .WithTracing(t => t.AddSource( "Npgsql", "Azure.Messaging.ServiceBus.*", "Aspire.RabbitMQ.Client", "RabbitMQ.Client.Publisher", "RabbitMQ.Client.Subscriber", "OpenTelemetry.Instrumentation.ConfluentKafka", "OpenTelemetry.Instrumentation.StackExchangeRedis")) .WithMetrics(m => m.AddMeter( "Npgsql", "MySqlConnector", "Aspire.Confluent.Kafka", "OpenTelemetry.Instrumentation.ConfluentKafka"));

注意 RabbitMQ v7+ 的 Publisher/Subscriber 数据源仅在对应客户端版本下存在，老版本项目注册这些 Source 也不会产生数据。

2. 按日志类别精细化筛选

以 Npgsql 为例，在appsettings.json中按类别控制日志级别：

{ "Logging": { "LogLevel": { "Default": "Information", "Npgsql.Command": "Debug", "Npgsql.Connection": "Debug", "MongoDB.Command": "Debug", "Microsoft.EntityFrameworkCore.Database.Command": "Debug" } } }

EF Core 系组件把 SQL 命令日志放在Microsoft.EntityFrameworkCore.Database.Command，而底层驱动的追踪独立走 Activity Source，两者可以分开观测、互不干扰。

3. 在 Aspire Dashboard 中检索

Aspire Dashboard 会汇总应用上报的 traces、metrics 与日志。排查问题时，可直接按本清单中的 Activity Source 名称过滤 trace 列表（例如输入Npgsql或Azure.Messaging.ServiceBus.*匹配的服务名），按 metric 名称搜索指标曲线（例如 Kafka 的messaging.kafka.consumer.queue.message_count可直观反映消费积压）。日志类别则体现在日志条目的 Category 字段中，可用于确认某条日志来自底层客户端库还是 EF Core 层。

清单之外：从源码读到的三个设计规律

1. "组件自带 Meter + 透传底层 Meter"双轨制：Kafka 是典型代表——Aspire.Confluent.Kafka自建 Meter 上报 librdkafka 原始统计（网络收发、消息收发、队列深度），同时透传OpenTelemetry.Instrumentation.ConfluentKafka的标准语义指标（publish/receive 时长与数量）。配置面板时若发现某个 Kafka 指标查不到，先确认它属于哪一条 Meter 轨。
2. 日志类别与 Activity Source 的命名空间往往不同源：如 SqlServer 组件日志走Microsoft.EntityFrameworkCore.*，追踪却走OpenTelemetry.Instrumentation.SqlClient；Pomelo 组件日志走 EF Core 类别，追踪与指标却走MySqlConnector。按"层"而非按"组件"记忆，更容易理解清单结构。
3. none是有意的设计声明：原文档对每个不支持项都标注了原因（如 "currently not supported by the Azure SDK"），说明这些组件的遥测能力上限由底层库决定，Aspire 层不做虚构补齐。

结语

本清单覆盖了 Aspire 仓库src/Components下 30 余个主流组件的全部日志类别、Activity Source 与 Metric 名称，是配置 OpenTelemetry 管道、搭建监控面板与排查可观测性问题的直接速查表。配合各组件源码（如 AspirePostgreSqlNpgsqlExtensions.cs、AspireRedisExtensions.cs、ConfluentKafkaMetrics.cs）与 docs/open-telemetry-architecture.md 架构文档，可以快速定位任意组件的遥测实现细节，并在自己的应用中按需裁剪、聚合与告警。

【免费下载链接】aspireAspire is the tool for code-first, extensible, observable dev and deploy.项目地址: https://gitcode.com/GitHub_Trending/as/aspire