Merge pull request RustPython#1126 from RustPython/coolreader18/flamescope-profiling

Add an speedscope output format for profiling

Author: windelbouwman

.gitignore

@@ -10,4 +10,7 @@ __pycache__
 wasm-pack.log
 .idea/
 tests/snippets/resources
+
 flame-graph.html
+flame.txt
+flamescope.json

Cargo.lock

@@ -16,7 +16,7 @@ path = "./benchmarks/bench.rs"
 
 [features]
 default = []
-flame-it = ["rustpython-vm/flame-it", "flame"]
+flame-it = ["rustpython-vm/flame-it", "flame", "flamescope"]
 
 [dependencies]
 log="0.4.1"
@@ -29,6 +29,7 @@ rustyline = "4.1.0"
 xdg = "2.2.0"
 
 flame = { version = "0.2", optional = true }
+flamescope = { version = "0.1", optional = true }
 
 [dev-dependencies.cpython]
 version = "0.2"

Cargo.toml

@@ -0,0 +1,56 @@
+# RustPython Development Guide and Tips
+
+## Code organization
+
+- `parser/src`: python lexing, parsing and ast
+- `vm/src`: python virtual machine
+  - `builtins.rs`: Builtin functions
+  - `compile.rs`: the python compiler from ast to bytecode
+  - `obj`: python builtin types
+- `src`: using the other subcrates to bring rustpython to life.
+- `docs`: documentation (work in progress)
+- `py_code_object`: CPython bytecode to rustpython bytecode converter (work in
+  progress)
+- `wasm`: Binary crate and resources for WebAssembly build
+- `tests`: integration test snippets
+
+## Code style
+
+The code style used is the default
+[rustfmt](https://github.com/rust-lang/rustfmt) codestyle. Please format your
+code accordingly. We also use [clippy](https://github.com/rust-lang/rust-clippy)
+to detect rust code issues.
+
+## Testing
+
+To test rustpython, there is a collection of python snippets located in the
+`tests/snippets` directory. To run those tests do the following:
+
+```shell
+$ cd tests
+$ pipenv install
+$ pipenv run pytest -v
+```
+
+There also are some unit tests, you can run those with cargo:
+
+```shell
+$ cargo test --all
+```
+
+## Profiling
+
+To profile rustpython, simply build in release mode with the `flame-it` feature.
+This will generate a file `flamescope.json`, which you can then view at
+https://speedscope.app.
+
+```sh
+$ cargo run --release --features flame-it script.py
+$ cat flamescope.json
+{<json>}
+```
+
+You can also pass the `--output-file` option to choose which file to output to
+(or stdout if you specify `-`), and the `--output-format` option to choose if
+you want to output in the speedscope json format (default), text, or a raw html
+viewer (currently broken).

DEVELOPMENT.md

@@ -59,19 +59,6 @@ Documentation HTML files can then be found in the `target/doc` directory.
 
 If you wish to update the online documentation, push directly to the `release` branch (or ask a maintainer to do so). This will trigger a Travis build that updates the documentation and WebAssembly demo page.
 
-# Code organization
-
-- `parser/src`: python lexing, parsing and ast
-- `vm/src`: python virtual machine
-  - `builtins.rs`: Builtin functions
-  - `compile.rs`: the python compiler from ast to bytecode
-  - `obj`: python builtin types
-- `src`: using the other subcrates to bring rustpython to life.
-- `docs`: documentation (work in progress)
-- `py_code_object`: CPython bytecode to rustpython bytecode converter (work in progress)
-- `wasm`: Binary crate and resources for WebAssembly build
-- `tests`: integration test snippets
-
 # Contributing
 
 Contributions are more than welcome, and in many cases we are happy to guide contributors through PRs or on gitter.
@@ -88,23 +75,6 @@ You can also simply run
 `./whats_left.sh` to assist in finding any
 unimplemented method.
 
-# Testing
-
-To test rustpython, there is a collection of python snippets located in the
-`tests/snippets` directory. To run those tests do the following:
-
-```shell
-$ cd tests
-$ pipenv install
-$ pipenv run pytest -v
-```
-
-There also are some unit tests, you can run those with cargo:
-
-```shell
-$ cargo test --all
-```
-
 # Using a standard library
 
 As of now the standard library is under construction. You can
@@ -126,11 +96,6 @@ the [ouroboros library](https://github.com/pybee/ouroboros).
 
 [See this doc](wasm/README.md)
 
-# Code style
-
-The code style used is the default [rustfmt](https://github.com/rust-lang/rustfmt) codestyle. Please format your code accordingly.
-We also use [clippy](https://github.com/rust-lang/rust-clippy) to detect rust code issues.
-
 # Community
 
 Chat with us on [gitter][gitter].

README.md

@@ -22,13 +22,8 @@ use std::path::PathBuf;
 use std::process;
 
 fn main() {
-    if let Err(err) = run() {
-        error!("Error: {}", err);
-        process::exit(1);
-    }
-}
-
-fn run() -> Result<(), Box<dyn std::error::Error>> {
+    #[cfg(feature = "flame-it")]
+    let main_guard = flame::start_guard("RustPython main");
     env_logger::init();
     let app = App::new("RustPython")
         .version(crate_version!())
@@ -55,15 +50,19 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
         )
         .arg(Arg::from_usage("[pyargs] 'args for python'").multiple(true));
     #[cfg(feature = "flame-it")]
-    let app = app.arg(
-        Arg::with_name("profile_output")
-            .long("profile-output")
-            .takes_value(true)
-            .help(
-                "the file to output the profile graph to. present due to being \
-                 built with feature 'flame-it'",
-            ),
-    );
+    let app = app
+        .arg(
+            Arg::with_name("profile_output")
+                .long("profile-output")
+                .takes_value(true)
+                .help("the file to output the profiling information to"),
+        )
+        .arg(
+            Arg::with_name("profile_format")
+                .long("profile-format")
+                .takes_value(true)
+                .help("the profile format to output the profiling information in"),
+        );
     let matches = app.get_matches();
 
     // Construct vm:
@@ -90,16 +89,53 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
 
     #[cfg(feature = "flame-it")]
     {
-        use std::fs::File;
+        main_guard.end();
+        if let Err(e) = write_profile(matches) {
+            error!("Error writing profile information: {}", e);
+            process::exit(1);
+        }
+    }
+}
 
-        let profile_output = matches
-            .value_of_os("profile_output")
-            .unwrap_or_else(|| "flame-graph.html".as_ref());
-        if profile_output == "-" {
-            flame::dump_stdout();
-        } else {
-            flame::dump_html(&mut File::create(profile_output)?)?;
+#[cfg(feature = "flame-it")]
+fn write_profile(matches: clap::ArgMatches) -> Result<(), Box<dyn std::error::Error>> {
+    use std::fs::File;
+
+    enum ProfileFormat {
+        Html,
+        Text,
+        Speedscope,
+    }
+
+    let profile_output = matches.value_of_os("profile_output");
+
+    let profile_format = match matches.value_of("profile_format") {
+        Some("html") => ProfileFormat::Html,
+        Some("text") => ProfileFormat::Text,
+        None if profile_output == Some("-".as_ref()) => ProfileFormat::Text,
+        Some("speedscope") | None => ProfileFormat::Speedscope,
+        Some(other) => {
+            error!("Unknown profile format {}", other);
+            process::exit(1);
         }
+    };
+
+    let profile_output = profile_output.unwrap_or_else(|| match profile_format {
+        ProfileFormat::Html => "flame-graph.html".as_ref(),
+        ProfileFormat::Text => "flame.txt".as_ref(),
+        ProfileFormat::Speedscope => "flamescope.json".as_ref(),
+    });
+
+    let profile_output: Box<dyn std::io::Write> = if profile_output == "-" {
+        Box::new(std::io::stdout())
+    } else {
+        Box::new(File::create(profile_output)?)
+    };
+
+    match profile_format {
+        ProfileFormat::Html => flame::dump_html(profile_output)?,
+        ProfileFormat::Text => flame::dump_text_to_writer(profile_output)?,
+        ProfileFormat::Speedscope => flamescope::dump(profile_output)?,
     }
 
     Ok(())

src/main.rs

@@ -271,11 +271,6 @@ impl Frame {
     // #[cfg_attr(feature = "flame-it", flame("Frame"))]
     pub fn run(&self, vm: &VirtualMachine) -> Result<ExecutionResult, PyObjectRef> {
         flame_guard!(format!("Frame::run({})", self.code.obj_name));
-        // flame doesn't include notes in the html graph :(
-        flame_note!(
-            flame::StrCow::from("CodeObj name"),
-            self.code.obj_name.clone().into()
-        );
 
         let filename = &self.code.source_path.to_string();
 
@@ -342,10 +337,11 @@ impl Frame {
 
     /// Execute a single instruction.
     #[allow(clippy::cognitive_complexity)]
-    #[cfg_attr(feature = "flame-it", flame("Frame"))]
     fn execute_instruction(&self, vm: &VirtualMachine) -> FrameResult {
         let instruction = self.fetch_instruction();
 
+        flame_guard!(format!("Frame::execute_instruction({:?})", instruction));
+
         #[cfg(feature = "vm-tracing-logging")]
         {
             trace!("=======");

vm/src/frame.rs

@@ -273,14 +273,3 @@ macro_rules! flame_guard {
         let _guard = ::flame::start_guard($name);
     };
 }
-
-macro_rules! flame_note {
-    ($name:expr, $desc:expr$(,)?) => {
-        #[cfg(feature = "flame-it")]
-        ::flame::note($name, ::std::option::Option::Some($desc));
-    };
-    ($name:expr$(,)?) => {
-        #[cfg(feature = "flame-it")]
-        ::flame::note($name, ::std::option::Option::None);
-    };
-}