cx-profiling

性能剖析技能

通过 Coralogix 性能剖析 API，回答持续性能剖析问题：哪些服务消耗的 CPU 或内存最多，以及服务内部哪些函数是主要原因。需要 profiles.cpu-profiles:Read 权限。

CLI 命令

命令	用途	关键标志
cx profiling services	按 CPU + 墙钟秒数（cpu）或已分配字节数 + 堆字节数（memory）对已剖析的服务进行排名	--category（必需）、--environment、--limit（默认值为 20，最大值为 100）、--offset、--include-time-series
cx profiling metadata <service>	查看服务使用的语言，以及哪些性能剖析类型有数据	-
cx profiling filters <service>	查看服务的性能剖析可按哪些标签键筛选，以及这些标签键的值	--profile-type（必需）、--filter、--max-values-per-key（默认值为 50）
cx profiling metrics <service>	查看某种性能剖析类型随时间变化的用量，可按 service、pod 或任意标签拆分；按总量从高到低排序	--profile-type（必需）、--sum-by（默认值为 service）、--max-buckets（默认值为 60）、--limit（默认值为 10）、--filter
cx profiling flame-graph <service>	查看解码后的火焰图，以及按自身值排序的顶级函数	--profile-type（必需）、--filter、--top-functions（默认值为 20）、--min-node-ratio（默认值为 0.01）、--max-depth、--show-kernel

• 所有命令均为只读，并支持 -o json / -o toon。
• 每个命令都接受 --start / --end（默认值为 now-1h / now）：now、now-1h 这类相对表达式，或 ISO-8601 时间戳。
• --profile-type 可选值为 cpu、wall、memory-allocation-bytes、memory-allocation-objects、memory-heap-bytes、memory-heap-objects（不区分大小写；也支持 MEMORY_HEAP_BYTES）。请先检查 metadata——只有 has_data: true 的类型才会返回结果。
• --filter 可重复使用，多个筛选条件会以 AND 方式组合：key=v1,v2（匹配任一值）、key!=v1,v2（不匹配其中任何值）、key:exists、key:not-exists。使用 filters 查找键和值。
• services --environment 会匹配 deployment.environment.name；这是服务排名唯一支持的筛选条件。
• services 会对排名结果分页：若当前页已满，CLI 会打印下一页要使用的 --offset。除非传入 --include-time-series，否则不会返回时间序列。
• 对大型服务运行 flame-graph 可能需要约 40 秒；不要设置过短的 --http-timeout。

调查工作流

1. 找出负载最高的服务（如果用户已指定服务，则跳过）：

   cx profiling services --category cpu --limit 10 -o json
   cx profiling services --category memory --environment <env> --limit 10 -o json
   

2. 检查服务有哪些性能剖析类型：

   cx profiling metadata <service> -o json
   

3. 查看可用于筛选或拆分的字段（pod、版本、环境等）：

   cx profiling filters <service> --profile-type cpu -o json
   

4. 查找用量变化的时间，以及导致变化的对象——按 pod 或第 3 步中的标签键拆分：

   cx profiling metrics <service> --profile-type cpu --sum-by pod --limit 5 -o json
   cx profiling metrics <service> --profile-type cpu --sum-by service.version --start now-24h -o json
   

5. 找出问题所在代码——先查看顶级函数，再查看树：

   cx profiling flame-graph <service> --profile-type cpu --top-functions 10 -o json | jq '.top_functions'
   cx profiling flame-graph <service> --profile-type cpu --filter k8s.pod.name=<pod> \
     --min-node-ratio 0.05 --max-depth 20 -o json
   

阅读输出

• 服务：cpu 行包含 total_cpu_seconds / total_wall_seconds；memory 行包含 total_memory_allocations_bytes / total_heap_bytes。last_active 是以秒为单位的 Unix 时间戳。
• 指标：series 按 total（各时间桶总量之和）排名，并截取至 --limit；total_series 是服务端返回的序列数量。unit 根据性能剖析类型为 seconds、bytes 或 objects。
• 火焰图：top_functions 会对整棵树中的每个函数 + 文件累计自身值，因此不受树裁剪影响。tree 节点包含 function、file、line、self、total、self_percent、total_percent 和 children（按 total 从高到低排序）。omitted_subtrees 表示因 --min-node-ratio / --max-depth 而被移除的节点数。服务端已剪除低于总量 0.1% 的节点。无符号的栈帧会显示其地址或 unknown。warnings（例如 maxBytes）表示服务端提前停止读取性能剖析数据，因此图表只覆盖部分时间范围。

核心原则

• 先排序，再深入分析 — services 和 metrics 的开销很低； flame-graph 调用开销较大，因此请求前应先缩小服务、分析类型、 时间范围和筛选条件。
• 大型树结构体积很大 — 深层调用栈（Java、Scala）可能会生成数百 KB 的 JSON。提高树结构的 --min-node-ratio 或设置 --max-depth， 也可以只读取 .top_functions。
• 自身与总计 — self 值高表示函数本身很繁忙；total 值高而 self 值低表示开销在其调用的函数中。
• 结果为空不代表出错 — 对于所选分析类型或时间范围没有数据的服务， 会返回空序列或总计为零的图；请重新检查 metadata 并扩大 --start 范围。
• 没有分析数据 — 如果 metadata 显示没有任何分析类型的 has_data: true，则该服务未启用分析。不要查找其他服务名称：根据 cx-service-catalog 或 cx-telemetry-querying（CPU 或内存用量、 时间、pod）作答，并说明该服务需要启用分析才能获取函数级别的详情。
• 多分析类型扇出适用于每个子命令：重复使用 -p <profile>； 指定多个分析类型时，结果会带有 profile 标签。

相关技能

• cx-service-catalog — 获取相同服务的 RED 指标（延迟、错误）； 将此处发现的延迟回归与 CPU 峰值关联起来。
• cx-telemetry-querying — 针对分析发现的服务或 pod，进一步查看 日志、跨度或 PromQL 指标（cx logs、cx spans、cx metrics）。
• cx-infra — 当繁忙的 pod 指向基础设施问题时，检查主机和容器的健康状况。