进阶 oclif.io 2026-10-18 02:37:03 · 31 阅读
第38章 oclif 性能追踪详解
# 性能
oclif 开箱即用地支持性能追踪,既能监控 oclif 自身,也能监控你的自定义代码。根据 bin 脚本的实现方式,你可以通过以下两种方式之一启用它。
如果你使用的是脚手架生成器自带的 bin 脚本,只需在 settings 模块上设置 performanceEnabled:
如何启用
#!/usr/bin/env node
import {execute, settings} from '@oclif/core'
settings.performanceEnabled = true
await execute({dir: import.meta.url})
如果更适合你的 CLI,也可以直接在 Config 类上启用: import {Config, run} from '@oclif/core'
import {fileUrlToPath} from 'node:url'
const config = await Config.load({
root: resolve(fileURLToPath(import.meta.url), '..');,
enablePerf: true
})
await run(config)
访问 oclif 专属性能指标 启用性能追踪后,可以在 oclif:perf 作用域下的 debug 输出中查看这些指标。 ❯ DEBUG=oclif:perf sf version
@salesforce/cli/2.35.6 darwin-arm64 node-v20.11.0
oclif:perf Process Uptime: 747.6823ms +0ms
oclif:perf Oclif Time: 302.1286ms +0ms
oclif:perf Init Time: 37.7735ms +0ms
oclif:perf Config Load Time: 294.5321ms +0ms
oclif:perf • Root Plugin Load Time: 11.2781ms +0ms
oclif:perf • Plugins Load Time: 274.6006ms +0ms
oclif:perf • Commands Load Time: 6.7736ms +0ms
oclif:perf Core Plugin Load Time: 20.9403ms +0ms
oclif:perf User Plugin Load Time: 0.0000ms +0ms
oclif:perf Linked Plugin Load Time: 2.3124ms +0ms
oclif:perf Plugin Load Times: +0ms
oclif:perf oclif-hello-world: 239.1951ms (no manifest!) +0ms
oclif:perf @oclif/plugin-update: 18.8549ms +0ms
oclif:perf @oclif/plugin-autocomplete: 17.5277ms +0ms
oclif:perf @oclif/plugin-commands: 16.4917ms +0ms
oclif:perf @oclif/plugin-not-found: 16.3310ms +0ms
oclif:perf @oclif/plugin-search: 15.8846ms +0ms
oclif:perf @oclif/plugin-version: 14.8063ms +0ms
oclif:perf @salesforce/plugin-org: 14.5657ms +0ms
oclif:perf @salesforce/plugin-data: 14.3991ms +0ms
oclif:perf @oclif/plugin-warn-if-update-available: 14.3733ms +0ms
oclif:perf @oclif/plugin-which: 14.1629ms +0ms
oclif:perf @salesforce/plugin-apex: 13.9885ms +0ms
oclif:perf @salesforce/plugin-auth: 13.6895ms +0ms
oclif:perf @salesforce/plugin-deploy-retrieve: 13.6353ms +0ms
oclif:perf @salesforce/plugin-limits: 13.1123ms +0ms oclif:perf @salesforce/plugin-packaging: 12.9777ms +0ms
oclif:perf @salesforce/plugin-info: 12.7787ms +0ms
oclif:perf @salesforce/plugin-marketplace: 12.1542ms +0ms
oclif:perf @salesforce/plugin-source: 11.9480ms +0ms
oclif:perf @salesforce/plugin-schema: 11.7775ms +0ms
oclif:perf @salesforce/plugin-settings: 11.4785ms +0ms
oclif:perf @salesforce/plugin-templates: 11.4225ms +0ms
oclif:perf @salesforce/plugin-sobject: 11.3670ms +0ms
oclif:perf root: 11.2781ms +0ms
oclif:perf @salesforce/plugin-user: 10.8521ms +0ms
oclif:perf @salesforce/plugin-telemetry: 10.5724ms +1ms
oclif:perf @salesforce/plugin-trust: 10.4463ms +0ms
oclif:perf @oclif/plugin-plugins: 2.0135ms +0ms
oclif:perf @oclif/plugin-help: 1.9039ms +0ms
oclif:perf Hook Run Times: +0ms
oclif:perf init: +0ms
oclif:perf total: 37.4624ms +0ms
oclif:perf oclif-hello-world(./dist/hooks/init/init): 7.9818ms +0ms
oclif:perf @oclif/plugin-warn-if-update-available(./lib/hooks/init/check-update): 37.1145ms +0ms
oclif:perf @salesforce/plugin-settings(./lib/hooks/init/load_config_meta): 29.3073ms +0ms
oclif:perf @oclif/plugin-update(./dist/hooks/init.js): 33.1767ms +0ms
oclif:perf prerun: +0ms
oclif:perf total: 260.5702ms +0ms
oclif:perf @salesforce/cli(./dist/hooks/prerun): 2.3582ms +0ms
oclif:perf @salesforce/plugin-telemetry(./lib/hooks/telemetryPrerun.js): 260.2634ms +0ms
oclif:perf preparse: +0ms
oclif:perf total: 0.5351ms +0ms
oclif:perf @salesforce/cli(/dist/hooks/preparse): 0.5045ms +0ms
oclif:perf postrun: +0ms
oclif:perf total: 0.3507ms +0ms
oclif:perf Command Load Time: 0.7478ms +0ms
oclif:perf Command Run Time: 264.2587ms +0ms
你还可以通过编程方式访问这些指标,示例如下: const {Performance, flush, handle, run, settings} = await import('@oclif/core')
settings.performanceEnabled = true
await run(process.argv.slice(2))
.catch(async (error) => handle(error))
.finally(async () => {
console.log('Performance', Performance.oclifPerf)
await flush()
})
使用 Performance 监控代码 你还可以使用 Performance 类来捕获自身代码的性能指标。 若要测量某段代码的性能,需通过 Performance.mark 创建一个新的标记。随后,调用该标记的 .stop 方法以结束计时。 以下是一个简要示例: import {Performance} from '@oclif/core'
// 创建一个新标记。
// 第一个参数是标记的所有者(这有助于 Performance 区分每个标记的来源)
// 第二个参数是标记的名称。oclif 内部使用的命名约定为.#scope。不过,你可以自由决定命名方式。
const marker = Performance.mark('my-plugin', 'hello.run')
// 执行耗时操作。
// 向标记添加后续可能需要访问的详细信息
marker?.addDetails({from: flags.from, person: args.person})
// 停止标记。这将捕获从创建到停止标记之间的时间差。
marker?.stop()
下面是一个更完整的示例: // ./src/commands/hello/index.ts
import {Args, Command, Flags, Performance} from '@oclif/core'
export default class Hello extends Command {
static args = {
person: Args.string({description: 'Person to say hello to', required: true}),
}
static flags = {
from: Flags.string({char: 'f', description: 'Who is saying hello', required: true}),
}
async run(): Promise {
const {args, flags} = await this.parse(Hello)
const marker = Performance.mark('my-plugin', 'hello.run')
await new Promise((resolve) => {
setTimeout(resolve, 1000)
})
marker?.addDetails({from: flags.from, person: args.person})
marker?.stop()
this.log(`hello ${args.person} from ${flags.from}! (./src/commands/hello/index.ts)`)
}
}
你创建的所有标记都可以通过 Performance 的静态 results 属性访问: // bin/run.js
const {Performance, flush, handle, run, settings} = await import('@oclif/core')
settings.performanceEnabled = true
await run(process.argv.slice(2))
.catch(async (error) => handle(error))
.finally(async () => {
console.log('Results', Performance.results)
await flush()
})
❯ bin/run.js hello reader --from oclif
hello reader from oclif! (./src/commands/hello/index.ts)
Results Map(1) {
'my-plugin' => [
{
details: {
from: oclif,
person: reader
},
duration: 1003.4971249999999,
method: 'run',
module: 'hello',
name: 'hello.run',
scope: undefined
}
]
}
import {execute, settings} from '@oclif/core'
settings.performanceEnabled = true
await execute({dir: import.meta.url})
如果更适合你的 CLI,也可以直接在 Config 类上启用: import {Config, run} from '@oclif/core'
import {fileUrlToPath} from 'node:url'
const config = await Config.load({
root: resolve(fileURLToPath(import.meta.url), '..');,
enablePerf: true
})
await run(config)
访问 oclif 专属性能指标 启用性能追踪后,可以在 oclif:perf 作用域下的 debug 输出中查看这些指标。 ❯ DEBUG=oclif:perf sf version
@salesforce/cli/2.35.6 darwin-arm64 node-v20.11.0
oclif:perf Process Uptime: 747.6823ms +0ms
oclif:perf Oclif Time: 302.1286ms +0ms
oclif:perf Init Time: 37.7735ms +0ms
oclif:perf Config Load Time: 294.5321ms +0ms
oclif:perf • Root Plugin Load Time: 11.2781ms +0ms
oclif:perf • Plugins Load Time: 274.6006ms +0ms
oclif:perf • Commands Load Time: 6.7736ms +0ms
oclif:perf Core Plugin Load Time: 20.9403ms +0ms
oclif:perf User Plugin Load Time: 0.0000ms +0ms
oclif:perf Linked Plugin Load Time: 2.3124ms +0ms
oclif:perf Plugin Load Times: +0ms
oclif:perf oclif-hello-world: 239.1951ms (no manifest!) +0ms
oclif:perf @oclif/plugin-update: 18.8549ms +0ms
oclif:perf @oclif/plugin-autocomplete: 17.5277ms +0ms
oclif:perf @oclif/plugin-commands: 16.4917ms +0ms
oclif:perf @oclif/plugin-not-found: 16.3310ms +0ms
oclif:perf @oclif/plugin-search: 15.8846ms +0ms
oclif:perf @oclif/plugin-version: 14.8063ms +0ms
oclif:perf @salesforce/plugin-org: 14.5657ms +0ms
oclif:perf @salesforce/plugin-data: 14.3991ms +0ms
oclif:perf @oclif/plugin-warn-if-update-available: 14.3733ms +0ms
oclif:perf @oclif/plugin-which: 14.1629ms +0ms
oclif:perf @salesforce/plugin-apex: 13.9885ms +0ms
oclif:perf @salesforce/plugin-auth: 13.6895ms +0ms
oclif:perf @salesforce/plugin-deploy-retrieve: 13.6353ms +0ms
oclif:perf @salesforce/plugin-limits: 13.1123ms +0ms oclif:perf @salesforce/plugin-packaging: 12.9777ms +0ms
oclif:perf @salesforce/plugin-info: 12.7787ms +0ms
oclif:perf @salesforce/plugin-marketplace: 12.1542ms +0ms
oclif:perf @salesforce/plugin-source: 11.9480ms +0ms
oclif:perf @salesforce/plugin-schema: 11.7775ms +0ms
oclif:perf @salesforce/plugin-settings: 11.4785ms +0ms
oclif:perf @salesforce/plugin-templates: 11.4225ms +0ms
oclif:perf @salesforce/plugin-sobject: 11.3670ms +0ms
oclif:perf root: 11.2781ms +0ms
oclif:perf @salesforce/plugin-user: 10.8521ms +0ms
oclif:perf @salesforce/plugin-telemetry: 10.5724ms +1ms
oclif:perf @salesforce/plugin-trust: 10.4463ms +0ms
oclif:perf @oclif/plugin-plugins: 2.0135ms +0ms
oclif:perf @oclif/plugin-help: 1.9039ms +0ms
oclif:perf Hook Run Times: +0ms
oclif:perf init: +0ms
oclif:perf total: 37.4624ms +0ms
oclif:perf oclif-hello-world(./dist/hooks/init/init): 7.9818ms +0ms
oclif:perf @oclif/plugin-warn-if-update-available(./lib/hooks/init/check-update): 37.1145ms +0ms
oclif:perf @salesforce/plugin-settings(./lib/hooks/init/load_config_meta): 29.3073ms +0ms
oclif:perf @oclif/plugin-update(./dist/hooks/init.js): 33.1767ms +0ms
oclif:perf prerun: +0ms
oclif:perf total: 260.5702ms +0ms
oclif:perf @salesforce/cli(./dist/hooks/prerun): 2.3582ms +0ms
oclif:perf @salesforce/plugin-telemetry(./lib/hooks/telemetryPrerun.js): 260.2634ms +0ms
oclif:perf preparse: +0ms
oclif:perf total: 0.5351ms +0ms
oclif:perf @salesforce/cli(/dist/hooks/preparse): 0.5045ms +0ms
oclif:perf postrun: +0ms
oclif:perf total: 0.3507ms +0ms
oclif:perf Command Load Time: 0.7478ms +0ms
oclif:perf Command Run Time: 264.2587ms +0ms
你还可以通过编程方式访问这些指标,示例如下: const {Performance, flush, handle, run, settings} = await import('@oclif/core')
settings.performanceEnabled = true
await run(process.argv.slice(2))
.catch(async (error) => handle(error))
.finally(async () => {
console.log('Performance', Performance.oclifPerf)
await flush()
})
使用 Performance 监控代码 你还可以使用 Performance 类来捕获自身代码的性能指标。 若要测量某段代码的性能,需通过 Performance.mark 创建一个新的标记。随后,调用该标记的 .stop 方法以结束计时。 以下是一个简要示例: import {Performance} from '@oclif/core'
// 创建一个新标记。
// 第一个参数是标记的所有者(这有助于 Performance 区分每个标记的来源)
// 第二个参数是标记的名称。oclif 内部使用的命名约定为
const marker = Performance.mark('my-plugin', 'hello.run')
// 执行耗时操作。
// 向标记添加后续可能需要访问的详细信息
marker?.addDetails({from: flags.from, person: args.person})
// 停止标记。这将捕获从创建到停止标记之间的时间差。
marker?.stop()
下面是一个更完整的示例: // ./src/commands/hello/index.ts
import {Args, Command, Flags, Performance} from '@oclif/core'
export default class Hello extends Command {
static args = {
person: Args.string({description: 'Person to say hello to', required: true}),
}
static flags = {
from: Flags.string({char: 'f', description: 'Who is saying hello', required: true}),
}
async run(): Promise
const {args, flags} = await this.parse(Hello)
const marker = Performance.mark('my-plugin', 'hello.run')
await new Promise((resolve) => {
setTimeout(resolve, 1000)
})
marker?.addDetails({from: flags.from, person: args.person})
marker?.stop()
this.log(`hello ${args.person} from ${flags.from}! (./src/commands/hello/index.ts)`)
}
}
你创建的所有标记都可以通过 Performance 的静态 results 属性访问: // bin/run.js
const {Performance, flush, handle, run, settings} = await import('@oclif/core')
settings.performanceEnabled = true
await run(process.argv.slice(2))
.catch(async (error) => handle(error))
.finally(async () => {
console.log('Results', Performance.results)
await flush()
})
❯ bin/run.js hello reader --from oclif
hello reader from oclif! (./src/commands/hello/index.ts)
Results Map(1) {
'my-plugin' => [
{
details: {
from: oclif,
person: reader
},
duration: 1003.4971249999999,
method: 'run',
module: 'hello',
name: 'hello.run',
scope: undefined
}
]
}