/spark profiler
基本信息
| 属性 | 值 |
|---|---|
| 命令名 | profiler |
| 别名 | sampler |
| 来源 | me.lucko.spark.common.command.modules.SamplerModule（SamplerModule.java:78） |
| 允许子命令 | 是（.allowSubCommand(true)，SamplerModule.java:79） |
| 玩家权限 | 见 /spark —— 1.7.10 上为 OP / 服务器所有者 / 控制台 |
profiler 是 spark 的核心功能：在服务端（或客户端）主线程上挂一个采样器，收集 CPU 执行栈或内存分配采样，结束后上传到 spark 查看器或存成文件。
子命令
| 子命令 | 作用 | 代码位置 |
|---|---|---|
info |
打印当前采样器状态 | SamplerModule.java:114-117 |
start |
启动采样器 | SamplerModule.java:143-145 |
stop |
停止采样器并上传或存盘；upload 与 stop 完全等价 |
SamplerModule.java:138-141 |
cancel |
取消采样器且不产出结果 | SamplerModule.java:133-136 |
open |
边采样边通过 bytesocks 实时推送到查看器 | SamplerModule.java:119-122 |
trust-viewer |
信任一个待连接的查看器客户端 id | SamplerModule.java:128-131 |
不带子命令且无参数时等同于 info；带参数但无匹配子命令时落到 profilerStart（SamplerModule.java:149-155）。每个子命令同时接受对应的布尔 flag 形式（如 --info、--start），这是 Arguments.boolFlag 的通用行为。
start 参数
| 参数 | 类型 | 说明 |
|---|---|---|
--timeout |
int（秒） | 采样时长。<= 10 直接拒绝并提示「Please choose a value greater than 10」；< 30 警告精度会显著变差 |
--interval |
double（毫秒） | 采样间隔；<= 0 时回退到采样模式默认值 |
--thread |
字符串，可重复 | 只采样指定线程（Set<String> threads，多个 --thread 累加） |
--only-ticks-over |
int（毫秒） | 只记录超过该时长的 tick |
--regex |
布尔 | 线程名按正则而非精确匹配 |
--alloc |
布尔 | 切换到内存分配采样模式（SamplerMode.ALLOCATION） |
--alloc-live-only |
布尔 | 仅统计存活对象的分配 |
--force-java-sampler |
布尔 | 强制使用内置 Java 采样引擎而非 async-profiler |
--ignore-sleeping |
布尔 | 忽略休眠线程 |
--ignore-native |
布尔 | 忽略 native 栈帧 |
--combine-all / --not-combined |
布尔 | 合并/不合并父调用 |
--separate-parent-calls |
布尔 | 分离父调用（见下） |
--timeout 的两段校验在 SamplerModule.java:175-186。未传 --thread 时使用平台默认线程：Forge1710ServerSparkPlugin 用构造时捕获的当前线程（ThreadDumper.GameThread，Forge1710ServerSparkPlugin.java:83-84），客户端用 minecraft.mcThread（Forge1710ClientSparkPlugin.java:56）。
同一时刻只能有一个采样器（SamplerContainer）。若已有采样器在跑：新请求碰到后台采样器会先提示「Stopping the background profiler before starting…」并停掉它；碰到前台采样器则只打印 info 并放弃（SamplerModule.java:159-172）。
stop / upload 参数
| 参数 | 说明 |
|---|---|
--save-to-file |
不上传，直接写本地 .sparkprofile |
--comment |
给报告附加注释（Iterables.getFirst(arguments.stringFlag("comment"), null)） |
--separate-parent-calls |
切换 MergeMode：separateParentCalls 与 sameMethod（默认）二选一 |
停止后如果原本跑的是后台采样器，会自动重启它并提示可用 /spark profiler cancel 关闭（SamplerModule.java:181-189）。
输出
stop 的两条路径由 handleUpload 决定（SamplerModule.java:191-241）：
- 默认上传：POST 到 bytebin 端点，成功后回复可点击链接
viewerUrl + key，格式化为「Profiler stopped & upload complete!」 - 上传失败自动降级：捕获异常后回复「An error occurred whilst uploading the results. Attempting to save to disk instead.」并转存盘
--save-to-file：写入profile-<yyyy-MM-dd_HH.mm.ss>.sparkprofile，回复本地路径 + 查看器地址
每次结果都会写入活动日志（Activity.urlActivity 或 Activity.fileActivity）。
open 与 trust-viewer
open 建立一条经 bytesocks 的实时查看器连接（handleOpen，SamplerModule.java:243+），采样数据边采边推。trust-viewer --id <client id> 把一个待连接的客户端 id 标记为可信，写入 config.json 的 trustedKeys（SamplerModule.java:trustViewer → TrustedKeyStore.trustPendingKey），并向已连接的 socket 广播信任消息；id 不存在时回复「Unable to find pending client with id ‘…’」。不带 --id 时回复「Please provide a client id with ‘–id <client id>’.」。
数值
| 数值名 | 值 | 来源 |
|---|---|---|
EXECUTION 模式默认采样间隔 |
4 ms | SamplerMode.java（SamplerMode.EXECUTION 构造参数） |
ALLOCATION 模式默认采样间隔 |
524287 字节（512 KiB） | SamplerMode.java（SamplerMode.ALLOCATION 构造参数） |
--timeout 硬性下限 |
> 10 秒 | SamplerModule.java:176-179 |
--timeout 建议值 |
> 30 秒 | SamplerModule.java:181-184 |
| 命令超时看门狗 | 3 × 5 秒 = 15 秒 | SparkPlatform.executeCommand |
交互
| 触发 | 行为 |
|---|---|
已在采样时再次 start |
停掉后台采样器后重启；前台采样器则拒绝并打印当前状态 |
stop 时无采样器 |
回复「There isn’t an active profiler running.」 |
采样器在跑时 cancel |
直接丢弃结果，不上传不存盘 |
| 上传失败 | 自动回退存盘，并打印异常堆栈 |