feat: profiling (Spark)

Author: zlataovce

config/sidebar.paper.ts

@@ -36,6 +36,7 @@ const paper: SidebarsConfig = {
           items: [
             "admin/how-to/basic-troubleshooting",
             "admin/how-to/update",
+            "admin/how-to/profiling",
             "admin/how-to/aikars-flags",
             "admin/how-to/anti-xray",
             "admin/how-to/get-to-vanilla",

docs/paper/admin/how-to/profiling.md

@@ -0,0 +1,42 @@
+---
+slug: /profiling
+description: How to profile your Minecraft server.
+---
+
+# Profiling
+
+Profiling is a way to diagnose performance problems with your server.
+A profiler measures certain characteristics of a running server, e.g. how often a method is called
+and how much time it takes up in a single tick, how long and often the garbage collector runs and much more.
+
+## Timings
+
+Paper bundles the [Timings v2](https://timings.aikar.co/) profiler, however Timings has been unmaintained
+for multiple years and its reports are difficult to read for beginners. It has been deprecated in favor of
+Spark and turned off by default in 1.21, see [this discussion](https://github.com/PaperMC/Paper/discussions/10565)
+for more information.
+
+## Spark
+
+Starting with 1.21, Paper bundles the [Spark](https://spark.lucko.me/) profiler, which is the preferred way
+to profile Paper.
+
+To start profiling your server, run this command:
+```
+/spark profiler start --timeout 600
+```
+
+After 10 minutes, this will return a URL with a profiler report, which you can analyze yourself or provide
+to a developer of a plugin or the Paper support chats.
+
+:::warning
+
+_For the profiling to be effective, the issue you are diagnosing must be actively occurring._
+
+:::
+
+This is only a fraction of what Spark can do, so if you want to learn about the different features of Spark
+or learn to analyze reports yourself, check out Spark's documentation [here](https://spark.lucko.me/docs/).
+
+If you need help with analyzing a performance issue, please bring a Spark report to the
+[PaperMC Discord server](https://discord.gg/PaperMC) (#paper-help) for assistance.

docs/paper/admin/reference/system-properties.md

@@ -215,3 +215,8 @@ It also remaps plugin CB calls to remove the version information.
 
 - **default**: `false`
 - **description**: Disables plugin remapping introduced in 1.20.5 and everything involving automatic plugin conversion by commodore. For more information see the [userdev](../../dev/getting-started/userdev.mdx#1205-and-beyond) documentation and the official [announcement](https://discord.com/channels/289587909051416579/976631292747735080/1232740079097876570).
+
+#### paper.startSparkBackgroundProfilerImmediately
+
+- **default**: `false`
+- **description**: Starts the background profiler as soon as possible when set to true. Otherwise the background profiler starts once the server has finished starting up (when the `Done (X.XXXs)! For help, type "help"` message is sent in console).