profiler docs

Author: pfitzseb

docs/make.jl

@@ -27,6 +27,7 @@ makedocs(
             "Table Viewer"=>"userguide/grid.md",
             # "Understanding Code" => "userguide/understandingcode.md",
             "Linter"=>"userguide/linter.md",
+            "Profiler"=>"userguide/profiler.md",
             # "Tasks" => "userguide/tasks.md",
             "Debugging"=>"userguide/debugging.md",
             "Compiling Sysimages"=>"userguide/compilesysimage.md",

docs/src/images/profiler1.png

@@ -17,19 +17,3 @@ If you have any issues with this setup, check out the [FAQ](@ref) first. If it d
 ## User Manual
 
 The following pages are the user manual. These describe how to install and use the Julia extension on VS Code, along with answer questions most new users encounter.
-
-- [Running Code](https://www.julia-vscode.org/docs/stable/userguide/runningcode/)
-- [Julia Environments](https://www.julia-vscode.org/docs/stable/userguide/env/)
-- [Code Navigation](https://www.julia-vscode.org/docs/stable/userguide/codenavigation/)
-- [Editing Code](https://www.julia-vscode.org/docs/stable/userguide/editingcode/)
-- [Formatting Code](https://www.julia-vscode.org/docs/stable/userguide/formatter/)
-- [Plot Gallery](https://www.julia-vscode.org/docs/stable/userguide/plotgallery/)
-- [Data Grid](https://www.julia-vscode.org/docs/stable/userguide/grid/)
-- [Understanding Code](https://www.julia-vscode.org/docs/stable/userguide/understandingcode/)
-- [Linter](https://www.julia-vscode.org/docs/stable/userguide/linter/)
-- [Tasks](https://www.julia-vscode.org/docs/stable/userguide/tasks/)
-- [Debugging](https://www.julia-vscode.org/docs/stable/userguide/debugging/)
-- [Compiling Sysimages](https://www.julia-vscode.org/docs/stable/userguide/compilesysimage/)
-- [Julia Markdown Documents](https://www.julia-vscode.org/docs/stable/userguide/weave/)
-- [Remote Development](https://www.julia-vscode.org/docs/stable/userguide/remote/)
-- [Settings](https://www.julia-vscode.org/docs/stable/userguide/settings/)

docs/src/images/profiler2.png

@@ -0,0 +1,35 @@
+# Profiling code
+
+Julia comes with it's own [sampling profiler](https://docs.julialang.org/en/v1/stdlib/Profile/) and there are [various packages](https://github.com/timholy/FlameGraphs.jl) to visualize these profile traces.
+
+The VS Code extension comes with it's own profile viewer. Profiling the example function from the [ProfileView.jl readme](https://github.com/timholy/ProfileView.jl)
+```
+function profile_test(n)
+    for i = 1:n
+        A = randn(100,100,20)
+        m = maximum(A)
+        Am = mapslices(sum, A; dims=2)
+        B = A[:,:,5]
+        Bsort = mapslices(sort, B; dims=1)
+        b = rand(100)
+        C = B.*b
+    end
+end
+
+# compilation
+@profview profile_test(1)
+# pure runtime
+@profview profile_test(10)
+```
+shows a flame graph and inline annotations:
+![profiler 1](../images/profiler1.png)
+
+Clicking on any element in the flamegraph zooms in on that element; double clicking on the background (or using the "reset view" button in the upper right) will restore the initial view. Ctrl-Click to open the referenced file.
+
+The tooltip will tell you the number of samples collect in a certain frame as well as the percentage of the top-most displayed frame. There are some heuristics for special flags like garbage collection, dynamic dispatch, and more (these are also color coded).
+
+![flame graph](../images/profiler2.png)
+
+The inline view shows you how much of the parent frame's samples originate on which line (and also the flags, as above, when hovering over the start of the inline annotation):
+
+![inline](../images/profiler3.png)