生产环境性能分析

使用 Cloudflare 控制面板、Cloudflare CLI（命令行界面）或 Cloudflare API，为已部署的 Workers 和 Durable Objects 捕获 CPU 和内存分配性能分析数据。通过这些数据找出耗费资源的函数和分配内存的代码。

选择性能分析类型

使用 CPU 性能分析找出耗费 CPU 时间的函数。这是默认的分析类型。

使用 Heap 性能分析找出分配内存的代码。捕获期间每分配 512 kB 内存，它就会收集一次堆栈跟踪，记录造成该次采样分配的函数调用链。

Heap 性能分析测量的是内存分配量，而不是保留的内存。它不是堆快照，也不会显示已分配的内存是否仍在使用。

准备流量

您的 Worker 或 Durable Object 实例需要在捕获前和捕获期间接收流量。捕获会针对最近活跃且已加载的隔离环境，而不是启动新的调用。

发送能够运行您要调查的代码的请求。捕获性能分析数据不会替您调用代码。

历史日志的时间范围和筛选条件不会控制捕获。性能分析记录的是所选捕获时长内的活动，而不是日志中显示的过去请求。

启用源映射

捕获性能分析数据前请启用源映射，让火焰图显示可读的函数名称和文件位置，而不是压缩后的代码。如果 Worker 打包并压缩了代码，缺少源映射的堆栈帧会指向压缩后的代码包，难以阅读。

从 Wrangler 4.150.0 开始，Wrangler 默认会上传源映射。在较早版本中，请在 Wrangler 配置中将 upload_source_maps 设为 true，然后部署 Worker。详情请参阅源映射和堆栈跟踪。

捕获性能分析数据

使用控制面板

分析 Worker

在 Cloudflare 控制面板中，前往 Workers & Pages 并选择您的 Worker：
前往 Workers & Pages ↗
选择 可观测性。在视图下拉菜单中，选择 火焰图。
在 性能分析类型 中，选择 CPU 或 Heap。
在 时长 (ms) 中，输入 1000 至 50000 毫秒之间的捕获时长。默认值为 10000 毫秒。
在版本中，选择最新或当前部署中的某个版本。
选择 Capture profile。采集期间，按钮会显示 Capturing...。

分析 Durable Object

在 Cloudflare 控制面板中，前往 Durable Objects：
前往 Durable Objects ↗
选择您的命名空间，然后选择目标实例。
选择 可观测性。在视图下拉菜单中，选择 火焰图。
在 性能分析类型 中，选择 CPU 或 Heap。
在 时长 (ms) 中，输入 1000 至 50000 毫秒之间的捕获时长。默认值为 10000 毫秒。
在版本中，选择最新或当前部署中的某个版本。
选择 Capture profile。采集期间，按钮会显示 Capturing...。

捕获完成后，控制面板会以火焰图形式显示性能分析结果。

使用 Cloudflare CLI

捕获性能分析数据前，请安装 cf 并登录。如需选择目标账户，请参阅选择账户。

运行以下命令，查看性能分析命令的所有可用选项：

cf workers versions profile --help

该命令需要一个位置参数形式的版本标识符和 --worker-id。可使用 latest、版本的通用唯一标识符 (UUID)，或至少包含八个字符的 UUID 前缀。

latest 选择最近创建的版本，该版本不一定已部署。如果该版本未运行，请将示例中的 latest 替换为正在运行的版本标识符。

将 --duration-ms 设为 1000 至 50000 毫秒之间的值。对于 Worker 或 Durable Object，使用 --profile-type cpu 捕获 CPU 性能分析数据，或使用 --profile-type heap 捕获内存分配性能分析数据。

该命令会将原始二进制 pprof 数据写入标准输出。

分析 Worker

将 $WORKER_ID 设为 Worker ID 或名称。
确保运行所选版本的 Worker 持续接收流量。

捕获 5 秒的 CPU 性能分析数据，并保存为 worker-cpu.pprof：

cf workers versions profile latest \
  --worker-id "$WORKER_ID" \
  --duration-ms 5000 \
  --profile-type cpu > worker-cpu.pprof

分析 Durable Object

将 $WORKER_ID 设为拥有该 Durable Object 命名空间的 Worker 的 ID 或名称，而不是仅通过绑定调用它的 Worker。

将 $NAMESPACE_ID 设为命名空间 ID，并将 $DURABLE_OBJECT_ID 设为 64 个十六进制字符组成的实例 ID。
确保目标实例持续接收流量，且处于活跃状态并运行所选 Worker 版本。

捕获 5 秒的 Heap 性能分析数据并保存为 durable-object-heap.pprof。同时传入 --namespace-id 和 --actor-id，以便精确定位该实例：

cf workers versions profile latest \
  --worker-id "$WORKER_ID" \
  --duration-ms 5000 \
  --profile-type heap \
  --namespace-id "$NAMESPACE_ID" \
  --actor-id "$DURABLE_OBJECT_ID" > durable-object-heap.pprof

使用 API

使用具有 Workers Scripts Read 权限的 API 令牌，或具有 Content Read-Only Workers 角色的令牌。将 $CLOUDFLARE_API_TOKEN 设为您的令牌，并将 $ACCOUNT_ID 设为账户 ID。

latest 版本指最近创建的版本，而不一定是已部署的版本。如果您上传了较新版本但尚未部署，请将 URL 中的 latest 替换为已部署版本的 UUID。

所选版本必须已加载并运行，而且捕获期间须有流量。API 会返回 gzip 压缩的 pprof 性能分析数据。

在请求正文中使用以下字段：

字段	含义
`duration_ms`	必填整数，范围为 `1000` 至 `50000` 毫秒。
`profile_type`	可选：`cpu`（默认值）或 `heap`。
`namespace_id`	Durable Object 命名空间 ID。捕获 Durable Object 时，必须与 `actor_id` 一起提供。
`actor_id`	Durable Object 实例 ID，由 64 个十六进制字符组成。捕获 Durable Object 时，必须与 `namespace_id` 一起提供。

分析 Worker

将 $WORKER_ID 设为 Worker ID 或名称。
向运行所请求版本的 Worker 发送流量。

发送 POST 请求以捕获性能分析数据。此示例捕获 10 秒的 CPU 性能分析数据，并保存为 worker-cpu.pprof.gz。

curl --fail --silent --show-error --request POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/workers/$WORKER_ID/versions/latest/profile" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "duration_ms": 10000
  }' \
  --output worker-cpu.pprof.gz

分析 Durable Object

将 $WORKER_ID 设为拥有该 Durable Object 命名空间的 Worker 的 ID 或名称，而不是仅通过绑定调用它的 Worker。

将 $NAMESPACE_ID 设为命名空间 ID，并将 $DURABLE_OBJECT_ID 设为由 64 个十六进制字符组成的实例 ID。
向目标实例发送流量。确保它处于活跃状态并运行所请求的 Worker 版本。

同时传入 namespace_id 和 actor_id，发送 POST 请求。此示例捕获 10 秒的 Heap 性能分析数据，并保存为 durable-object-heap.pprof.gz。

若要捕获 CPU 性能分析数据，请将 profile_type 改为 cpu。

curl --fail --silent --show-error --request POST \
  "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/workers/workers/$WORKER_ID/versions/latest/profile" \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data "{
    \"duration_ms\": 10000,
    \"profile_type\": \"heap\",
    \"namespace_id\": \"$NAMESPACE_ID\",
    \"actor_id\": \"$DURABLE_OBJECT_ID\"
  }" \
  --output durable-object-heap.pprof.gz

查看结果

在控制面板的火焰图中，每一帧代表所捕获调用堆栈中的一个函数。调用方位于其调用的函数之上。

帧的宽度与 CPU 时间或已分配内存成正比，具体取决于性能分析类型。该图不是时间线：水平位置并不表示函数何时运行。

选择一帧可聚焦其子树。使用面包屑导航返回父帧，或选择 所有帧 重置视图。

使用 Search frames 搜索函数名称或源代码位置。切换到 Table 可比较以下值：

值	含义
自身	归因于该帧的 CPU 时间或已分配内存，不包括其后代帧
总计	归因于该帧及其后代帧的 CPU 时间或已分配内存
占性能分析数据的百分比	占整个捕获结果的比例

即使您聚焦于某个子树，百分比仍相对于整个捕获结果计算。

下载捕获结果

使用兼容 pprof 的工具查看通过 CLI、API 或控制面板捕获的性能分析数据。在控制面板中，选择 下载性能分析数据，下载原始 pprof 文件。

限制

捕获请求受到速率限制。超出限制时，API 会返回 HTTP 429。请等待一段时间再重试；如果响应包含 Retry-After 标头，请遵循该标头。

API 还可能返回以下错误消息：

错误消息	含义或处理方法
`No recent executions were found for this Worker.`	向所选 Worker 版本或目标 Durable Object 实例发送流量，然后重新尝试捕获。
`The Worker has no loaded isolate in its recent execution locations.`	向目标版本或 Durable Object 实例发送流量，然后重新尝试捕获。
`Worker profiling is unavailable in this environment.`	目标环境中无法使用性能分析功能。
`This Worker does not support runtime profiling.`	所选 Worker 不支持性能分析。
`The Worker runtime could not start profiling. Please try again.`	重新尝试捕获。