agilelabs-fx-docs main activity/overview.md

Activity 设计总览

AgileLabs Framework 基于 .NET System.Diagnostics.Activity 统一 TraceId/SpanId 管理，通过 AppBuildOptions.ActivityConfiguration 配置监听器和采样策略。

配置入口

  • ActivityConfiguration.DefaultIdFormat：默认 W3C 格式，兼容分布式追踪系统。
  • ActivityConfiguration.DefaultActivityListener：可以自定义 ShouldListenTo 与 Sample 逻辑，默认会监听所有匹配 TypeFinderAssemblyScanPattern 的 ActivitySource。
  • AppActivitySources：框架内置的 Activity Source（如 BackgroundService）。

与 WorkContext 集成

  • 每个 WorkContext 创建时，框架会启动一个 Activity，并将 TraceId/SpanId 写入 IRequestSession。
  • 在 HTTP 请求开始、后台任务、Hangfire Job 等场景，都能自动获取 Trace 信息。

自定义 Activity

using var scope = AgileLabContexts.Context.CreateScopeWithWorkContext();
using var activity = AppActivitySources.BackgroundService.StartActivity(
    name: nameof(StartMessageSchedulerAsync),
    kind: ActivityKind.Internal,
    parentId: null);
  • 通过 parentId 可以手动串联链路；如果为 null，则创建新的 Root Activity。
  • 活动结束 (Dispose) 后会自动写入日志，便于追踪耗时。

常见场景

  1. 后台作业：在 IHostedService 中使用 AppActivitySources.BackgroundService 追踪执行阶段。
  2. MemoryBus/Event：在事件处理器中获取当前 Activity.Current，便于记录跨线程链路。
  3. 外部调用：为 HttpClient/数据库调用创建子 Activity，结合日志输出上下文。

延伸阅读：