diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 58 |
1 files changed, 40 insertions, 18 deletions
@@ -1,23 +1,38 @@ # :zap: spark -Spark is a CPU profiling plugin based on sk89q's [WarmRoast profiler](https://github.com/sk89q/WarmRoast). +spark is a performance profiling plugin based on sk89q's [WarmRoast profiler](https://github.com/sk89q/WarmRoast). The latest downloads are [available on Jenkins](https://ci.lucko.me/job/spark/). ## What does it do? -Effectively, it monitors the activity of the server, and records statistical data about which actions take up the most processing time. These statistics can then be used to diagnose potential performance issues with certain parts of the server or specific plugins. +spark is made up of a number of components, each detailed separately below. + +### CPU Profiler (process sampling) +This is the primary component of spark - a lightweight CPU sampler with corresponding web analysis view based on WarmRoast. + +The sampler records statistical data about which actions take up the most processing time. These statistics can then be used to diagnose potential performance issues with certain parts of the server or specific plugins. Once the data has been recorded, a "call graph" can be formed and displayed in a web browser for analysis. -spark will not fix "lag" - it is a tool to help diagnose the cause of poor performance. +A profiler like the one in spark will not magically fix "lag" - they are merely a tool to help diagnose the cause of poor performance. + +### Tick Monitor (server tick monitoring) + +This component monitors the speed at which the game server is processing "ticks". Can be used to spot trends and identify the nature of a performance issue, relative to other system events. (garbage collection, game actions, etc) + +### Memory Inspection (heap analysis & GC monitoring) -## About +This component provides a function which can be used to take basic snapshots of system memory usage, including information about potentially problematic classes, estimated sizes and instance counts corresponding to objects in the JVM. + +Unlike the other "profiler"-like functionality in spark, this component is *not* intended to be a full replacement for proper memory analysis tools. It just shows a simplified view. + +## Features ### WarmRoast features These features are carried over from the upstream "WarmRoast" project. -* The viewer is entirely web-based— no specialist software is required to view the output, just a web browser! +* The viewer is entirely web-based — no specialist software is required to view the output, just a web browser! * Output is arranged as a stack of nested method calls, making it easy to interpret the output * Nodes can be expanded and collapsed to reveal timing details and further child nodes. * The overall CPU usage and contribution of a particular method can be seen at a glance. @@ -29,14 +44,15 @@ These features are carried over from the upstream "WarmRoast" project. WarmRoast is an amazing tool for server admins, but it has a few flaws. -* It is not accessible to some people, because in order to use it, you need to have direct SSH (or equivalent) access to the server. (not possible on shared hosts) -* It can be somewhat clunky to setup and start - firstly, you need to connect to the machine of the server you want to profile. Then, you need to remember the PID of the server, or identify it in a list of running VM display names (not easy when multiple servers are running!) - then allow the profiler to run for a bit, before navigating to a temporary web server hosted by the application. +* It is not accessible to some users, because in order to use it, you need to have direct SSH (or equivalent) access to the server. (not possible on shared hosts) +* It can be somewhat clunky to setup and start (typical steps: ssh into server machine, open up ports / disable firewall rules?, start process, identify target VM, allow profiler to run for a bit, open a web browser & navigate to the temporary web page hosted by the application. not ideal!) * It's not easy to share profiling data with other developers or admins. -* You need to have the Java Development Kit installed on your machine. +* Java Development Kit must be installed on the target machine. I've attempted to address these flaws in spark. -* Profiling is managed entirely using in-game or console commands. You don't need to have direct access to the server machine - just install the plugin as you would normally. +* Profiling is managed entirely using in-game or console commands. +* You don't need to have direct access to the server machine - just install the plugin as you would normally. * Data is uploaded to a "pastebin"-esque site to be viewed - a temporary web server is not needed, and you can easily share your analysis with others! * It is not necessary to install any special Java agents or provide a path to the Java Development Kit @@ -46,7 +62,7 @@ Other benefits of spark compared with other profilers: * This works for both partially deobfuscated Bukkit mappings, as well as for Sponge/Forge (Searge) mappings * No specialist software is required to view the output, just a web browser. -### How does it work? +### spark vs "Real Profilers" The spark (WarmRoast) profiler operates using a technique known as [sampling](https://en.wikipedia.org/wiki/Profiling_(computer_programming)#Statistical_profilers). A sampling profiler works by probing the target programs call stack at regular intervals in order to determine how frequently certain actions are being performed. In practice, sampling profilers can often provide a more accurate picture of the target program's execution than other approaches, as they are not as intrusive to the target program, and thus don't have as many side effects. Sampling profiles are typically less numerically accurate and specific than other profiling methods (e.g. instrumentation), but allow the target program to run at near full speed. @@ -59,7 +75,7 @@ Aikar's [timings](https://github.com/aikar/timings) system (built into Spigot an timings will generally be slightly more accurate than spark, but is (arguably?!) less useful, as each area of analysis has to be manually defined. -For example, timings might identify that a certain listener in plugin x is taking up a lot of CPU time processing the PlayerMoveEvent, but it won't tell you which part of the processing is slow. spark/WarmRoast on the other hand *will* show this information, right down to the name of the method call causing the bad performance. +For example, timings might identify that a certain listener in plugin x is taking up a lot of CPU time processing the PlayerMoveEvent, but it won't tell you which part of the processing is slow. spark/WarmRoast on the other hand *will* show this information, right down to the name of the method call causing the issue. ## Installation @@ -67,10 +83,12 @@ To install, add the **spark.jar** file to your servers plugins/mods directory, a ## Commands -All commands require the `spark.profiler` permission. +All commands require the `spark` permission. + +Note that `/sparkb`, `/sparkv`, and `/sparkc` must be used instead of `/spark` on BungeeCord, Velocity and Forge Client installs respectively. ___ -#### `/profiler start` +#### `/spark start` Starts a new profiling operation. **Arguments** @@ -90,25 +108,29 @@ Starts a new profiling operation. * `--only-ticks-over <tick length millis>` * Specifies that entries should only be included if they were part of a tick that took longer than the specified duration to execute. ___ -#### `/profiler info` +#### `/spark info` Prints information about the active profiler, if present. ___ -#### `/profiler stop` -Ends the current profiling operation, uploads the resultant data, and returns a link to view the call graph. +#### `/spark stop` +Ends the current profiling operation, uploads the resultant data, and returns a link to the viewer. ___ -#### `/profiler cancel` +#### `/spark cancel` Cancels the current profiling operation, and discards any recorded data without uploading it. ___ -#### `/profiler monitoring` +#### `/spark monitoring` Starts/stops the tick monitoring system. **Arguments** * `--threshold <percentage increase>` * Specifies the report threshold, measured as a percentage increase from the average tick duration. +___ +#### `/spark heap` +Creates a new memory (heap) dump, uploads the resultant data, and returns a link to the viewer. + ## License spark is a fork of [WarmRoast](https://github.com/sk89q/WarmRoast), which is [licensed under the GNU General Public License](https://github.com/sk89q/WarmRoast/blob/3fe5e5517b1c529d95cf9f43fd8420c66db0092a/src/main/java/com/sk89q/warmroast/WarmRoast.java#L1-L17). |