forked from davidmarkclements/0x
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
davidmarkclements
committed
Mar 16, 2018
1 parent
5920312
commit ac5c6e8
Showing
3 changed files
with
145 additions
and
115 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| # Programmatic API | ||
|
|
||
| ### `require('0x')(opts) => Promise -> assetPath` | ||
|
|
||
| The `opts` argument is an object, with the following properties: | ||
|
|
||
| #### `argv` (array) – required | ||
|
|
||
| Pass the arguments that the spawned Node process should receive. | ||
|
|
||
| #### `workingDir` (string) | ||
|
|
||
| The base directory where profile folders will be placed. | ||
|
|
||
| Default: process.cwd() | ||
|
|
||
| #### `pathToNodeBinary` (string) | ||
|
|
||
| The path to any node binary executable. This will be used to run execute | ||
| the script and arguments supplied in `argv`. | ||
|
|
||
| Default: Node executable according to the `PATH` environment variable. | ||
|
|
||
| #### `name` (string) | ||
|
|
||
| The name of the flamegraph HTML output file, without the extension. | ||
|
|
||
| Default: flamegraph | ||
|
|
||
| #### `title` (string) | ||
|
|
||
| Set the title to display in the flamegraph UI. | ||
|
|
||
| Default: argv joined by space | ||
|
|
||
| #### `visualizeOnly` (string) | ||
|
|
||
| Supply a path to a profile folder to build or rebuild visualization | ||
| from original stacks. | ||
|
|
||
| Default: undefined | ||
|
|
||
| #### `collectOnly` (boolean) | ||
|
|
||
| Don't generate the flamegraph, only create the Profile Folder, | ||
| with relevant outputs. | ||
|
|
||
| Default: false | ||
|
|
||
| #### `phase` (number) | ||
|
|
||
| Stage in initialization to begin aggregating stacks. | ||
|
|
||
| `phase: 0` visualizes from the very start, this includes bootstrapping | ||
| stacks and loading the application module tree (these can dominate the flamegraph). | ||
|
|
||
| `phase: 1` excludes core bootstrapping stacks, except the end of the boostrapping process | ||
| where the application module tree is loaded from the entry point. | ||
|
|
||
| `phase: 2` excludes all initialization, this renders the most pragmatic flamegraph for most | ||
| use cases. | ||
|
|
||
| Default: 2 | ||
|
|
||
| #### `mapFrames` (function) | ||
|
|
||
| Will override phase. A custom mapping function that receives | ||
| an array of frames and an instance of the Profiler (see [stacks-to-json-stack-tree](http://github.com/davidmarkclements/stacks-to-json-stack-tree)). | ||
|
|
||
| Takes the form `(frames, profiler) => Array|false`. | ||
|
|
||
| The `frames` parameter is an array of objects containing a `name` property. | ||
|
|
||
| Return `false` to remove the whole stack from the output, or return a | ||
| modified array to change the output. | ||
|
|
||
| #### `status` (function) | ||
|
|
||
| Is called with status messages from 0x internals - useful for logging | ||
| or displaying status in the console. | ||
|
|
||
| Default: ()=>{} (noop) | ||
|
|
||
| ### `kernelTracing` | ||
|
|
||
| Use an OS kernel tracing tool (perf on Linux or DTrace on macOS and SmartOS). | ||
| This will capture native stack frames (C++ modules and Libuv I/O), | ||
| but may result in missing stacks on Node 8. | ||
|
|
||
| See [kernel-tracing.md](kernel-tracing.md) for more information. | ||
|
|
||
| Default: false | ||
|
|
||
| #### `outputDir` (string) | ||
|
|
||
| Specify artifact output directory. This can be specified in template | ||
| form with possible variables being `{pid}`, `{timestamp}`, `{name}` | ||
| (based on the `name` option) and `{outputDir}`(variables | ||
| must be specified without whitespace, e.g. `{ pid }` is not supported). | ||
|
|
||
| Default: `{pid}.0x` | ||
|
|
||
| #### `outputHtml` (string) | ||
|
|
||
| Specify destination of the generated flamegraph HTML file. | ||
| This can be specified in template form with possible variables | ||
| being `{pid}`, `{timestamp}`, `{name}` (based on the `name` flag) and | ||
| `{outputDir}` (variables must be specified without whitespace, | ||
| e.g. `{ pid }` is not supported). It can also be set to `-` to | ||
| send the HTML output to STDOUT. | ||
|
|
||
| If either this or `name` is set to `-` then the HTML will go to STDOUT. | ||
|
|
||
| Default: `{outputDir}/{name}.html` | ||
|
|
||
| #### `treeDebug` (boolean) | ||
|
|
||
| Save the intermediate tree representation of captured trace output to a JSON | ||
| file. | ||
|
|
||
| Default: false | ||
|
|
||
| #### `kernelTracingDebug` (boolean) | ||
|
|
||
| Show output from DTrace or perf(1) tools. | ||
|
|
||
| Default: false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters