@kylincloud/flamegraph

一个可复用的火焰图 / 差分火焰图组件库（React 适配层），基于 Pyroscope flamegraph 思路，适用于 CPU / 内存等采样型 Profiling 数据。

说明：本包主要服务于内部项目，API 在 0.x 阶段可能会有不兼容调整，请以当前版本导出的实际 API 为准。

功能特性

• 支持单视图与 Diff 差分视图
• 支持表格 / 火焰图 / 表格 + 火焰图 / Sandwich 等布局
• 交互：悬停提示、点击缩放、滚轮缩放、拖拽平移、右键菜单
• 函数名搜索与高亮
• 内置 i18n，中英文自动切换
• 两轴主题：themePreset + themeMode，支持自动跟随宿主暗色状态
• 保留 colorMode 兼容，Web Worker 加速

安装

# npm
npm install @kylincloud/flamegraph

# pnpm
pnpm add @kylincloud/flamegraph

依赖 @kylincloud/flamegraph-core 已由本包内部引入，一般不需要在业务侧单独安装。

peer 依赖：

• react >= 16.14.0
• react-dom >= 16.14.0
• true-myth ^5.1.2
• zod ^3.11.6

快速上手

import React from 'react'
import { FlamegraphRenderer, Box } from '@kylincloud/flamegraph'

const profile = {
  version: 1,
  flamebearer: {
    names: ['total', 'fnA', 'fnB'],
    levels: [[0, 100, 0, 0]],
    numTicks: 100,
    maxSelf: 100,
  },
  metadata: {
    appName: 'demo',
    spyName: 'cpu',
    format: 'single',
    sampleRate: 100,
    units: 'samples',
  },
}

export default function App() {
  return (
    <Box themePreset="kylin" themeMode="auto">
      <FlamegraphRenderer
        profile={profile}
        themePreset="kylin"
        themeMode="auto"
        locale="zh-CN"
      />
    </Box>
  )
}

推荐使用 profile prop 而非 flamebearer。profile 会自动处理 delta 编码的解码。

主题模型

推荐使用新主题 API：

<FlamegraphRenderer
  profile={profile}
  themePreset="kylin"
  themeMode="auto"
/>

• themePreset?: 'default' | 'kylin'
• themeMode?: 'auto' | 'light' | 'dark'
• themeMode="auto" 会优先检查最近宿主节点上的暗色标记，并兼容 html.dark、data-theme="dark"、data-theme-mode="dark"、data-flamegraph-theme-mode="dark"
• FlamegraphRenderer 默认值为 themePreset="kylin"、themeMode="auto"
• Box 也支持同样的新主题参数；旧的 theme="dark" | "light" | "kylin" 继续可用

旧 API 继续兼容，映射关系如下：

• colorMode="dark" => themePreset="default" + themeMode="dark"
• colorMode="light" => themePreset="default" + themeMode="light"
• colorMode="kylin" => themePreset="kylin" + themeMode="light"
• 如果新旧 API 同时传入，themePreset / themeMode 优先

推荐宿主接入方式：

• 品牌皮肤固定为麒麟风格时，传 themePreset="kylin" themeMode="auto"
• 宿主不需要再手动根据 isDark 在 dark / kylin 之间切换
• 如果你还在用 Box 包裹火焰图，建议同步给 Box 传入同一套新主题参数

数据格式

interface Profile {
  version: number
  flamebearer: {
    names: string[]
    levels: number[][]
    numTicks: number
    maxSelf: number
    sampleRate?: number
    units?: string
    leftTicks?: number
    rightTicks?: number
  }
  metadata: {
    appName?: string
    spyName?: string
    format: 'single' | 'double'
    sampleRate: number
    units: string
  }
}

数据格式说明：

• 单视图（single）：每 4 个数字为一组 [offset, total, self, nameIndex]
• 差分视图（double）：每 7 个数字为一组 [leftOffset, leftTotal, leftSelf, rightOffset, rightTotal, rightSelf, nameIndex]