SuperAPI AI 工具集

startup-perf

通用与其它

查看项目

更新于 10-16 00:31

技能介绍

用途:在测量、验证或排查 Aspire 启动性能时,使用 CLI 自剖析采集流程。核心是隐藏 CLI 参数 --capture-profile,它会启动一个私有独立仪表盘收集器,为命令及其子 AppHost 进程启用仅剖析用的 OTEL 插桩,导出 trace 归档,然后以被包装命令的退出码退出。

主要能力:剖析为可选且与上报遥测分离,需设置 ASPIRE_PROFILING_ENABLED=true 或 1 启用。CLI 剖析 span 使用 Aspire.Cli.Profiling ActivitySource,托管剖析 span 使用 Aspire.Hosting.Profiling,DCP 启动 span 使用 dcp.startup 插桩范围。上报遥测不得携带剖析会话 ID、高基数剖析标签或剖析 span。

使用方式:需使用包含 --capture-profile 的 Aspire CLI 构建。仓库检出可执行 ./restore.sh 与 ./dotnet.sh build src/Aspire.Cli/Aspire.Cli.csproj /p:SkipNativeBuild=true。快速开始示例:./dotnet.sh exec artifacts/bin/Aspire.Cli/Debug/net11.0/aspire.dll run --project tests/TestingAppHost1/TestingAppHost1.AppHost/TestingAppHost1.AppHost.csproj --capture-profile --capture-profile-output artifacts/tmp/startup-profile/profile.zip --non-interactive。也可对任意 Aspire 命令采集,如 aspire ls --capture-profile --capture-profile-output artifacts/tmp/startup-profile/ls-profile.zip --non-interactive。省略输出路径时,CLI 在当前工作目录写入 aspire-profile-<timestamp>-<session>.zip。对长驻的 run 和 start,CLI 在启动后自动退出,并等待剖析数据稳定后再写导出。

选项:--capture-profile 为隐藏递归根选项;--capture-profile-output PATH 指定输出 zip 路径,相对路径以当前工作目录为根;--capture-profile-delay SECONDS 为可选预热延迟,默认 5 秒。

输出:捕获写入仪表盘导出 zip,含 traces/profile.json(来自私有收集器的 OTLP JSON trace 导出)。可用 unzip -l 查看,解压后用 jq 统计 scope 与 span 名称。预期包含 Aspire.Cli.Profiling、Aspire.Hosting.Profiling 及配置要求时的 dcp.startup span。

对比与限制:建议用独立 worktree 做基线与特性测量,比较 span 名称、时长、操作 ID、进程 ID、事件与 trace 关联;该流程产出工件,本身不是统计基准运行器。支持并行捕获,但须使用不同输出路径;若 AppHost 启动配置固定了仪表盘、资源服务或应用端口,并行 worktree 仍可能端口冲突。常见问题包括缺少 aspire-managed 仪表盘二进制、导出缺少 Hosting span、无 aspire.profiling.session_id、span 未关联到同一 trace 等,可按资料给出的排查方向处理。