feat: profiling (spark) (#447)

* feat: profiling (Spark)

* fix: rearrange

* fix: address comments

Co-authored-by: Riley Park <rileysebastianpark@gmail.com>

* feat: `spark.enabled` configuration key

* feat: `paper.preferSparkPlugin` property

* refactor: no more system properties

* feat: `plugins/spark` folder

---------

Co-authored-by: Riley Park <rileysebastianpark@gmail.com>

Author: zlataovce

config-specs/paper/paper-global.yml

@@ -355,6 +355,20 @@ spam-limiter:
     description: >-
       The number that the internal tab spam counter can reach until the server
       kicks the player for spam
+spark:
+  enabled:
+    default: "true"
+    description: Whether the bundled spark profiler should be enabled.
+  enable-immediately:
+    default: "false"
+    description: >-
+      Whether the bundled spark profiler should be enabled as soon as possible. This can be useful for profiling the server during startup.
+      By default, spark is enabled once the server has finished starting up (when the **Done (X.XXXs)! For help, type "help"** message is sent in the console).
+  prefer-spark-plugin:
+    default: "false"
+    description: >-
+      Whether the bundled spark profiler should be disabled in favor of a standalone plugin.
+      If the spark plugin is not found, the bundled version will be loaded regardless of the setting, unless it is [explicitly disabled](#spark_enabled).
 timings:
   enabled:
     default: "false"

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,50 @@
+---
+slug: /profiling
+description: How to profile your Paper 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.
+
+:::warning
+
+_For profiling to be effective, the issue you are diagnosing must be actively occurring._
+
+:::
+
+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.
+
+## 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 to a profiler report, which you can analyze yourself or provide
+to a developer of a plugin or the Paper support chats.
+
+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/).
+
+:::tip
+
+If you want to use a version of spark newer than the bundled one, simply place a standalone spark plugin JAR
+into the `plugins` directory and enable the [`spark.prefer-spark-plugin`](../reference/configuration/global-configuration.mdx#spark_prefer_spark_plugin)
+global configuration option.
+
+:::
+
+## Timings
+
+Paper also 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.

src/components/config/ConfigurationStructureDiagram.tsx

@@ -48,6 +48,14 @@ const folderData: ExplorerNode[] = [
         url: "https://forums.papermc.io/threads/important-dev-psa-future-removal-of-cb-package-relocation.1106/",
         external: true,
       },
+      {
+        name: "spark",
+        type: "folder",
+        description:
+          "Used to store configuration and data for the bundled spark profiler. (Learn more)",
+        url: "https://spark.lucko.me/docs/Configuration",
+        external: true,
+      },
     ],
   },
   {