Spark

https://spark.lucko.me/docs
Admin
Spark is a performance analysis tool for Minecraft servers, helping to identify and resolve lag...
Tokens:18,731
Snippets:79
Trust Score:7.8
Update:1 year ago
Show doc for...
Tokens:
Raw
### Client Installation

Source: https://spark.lucko.me/docs/Installation

Download the spark .jar file and place it in the client's mods folder. Control spark using the /sparkc command.

```java
Place spark-*.jar in client's mods folder.
Use /sparkc command.
```

--------------------------------

### Server Installation

Source: https://spark.lucko.me/docs/Installation

Download the spark .jar file and place it in the server's mods or plugins folder. spark will load on server restart. Control spark using the /spark command. Ensure you have the 'spark' permission or are a server operator.

```java
Place spark-*.jar in server's mods or plugins folder.
Restart server.
Use /spark command.
```

--------------------------------

### Proxy Installation

Source: https://spark.lucko.me/docs/Installation

Download the spark .jar file and place it in the proxy's plugin folder. spark will load on proxy restart. Control spark using /sparkb (BungeeCord) or /sparkv (Velocity). Ensure you have the 'spark' permission.

```java
Place spark-*.jar in proxy's plugin folder.
Restart proxy.
Use /sparkb or /sparkv command.
```

--------------------------------

### Install Hotspot Debug Symbols (Debian/Ubuntu)

Source: https://spark.lucko.me/docs/misc/Using-async-profiler

This command installs the necessary debug symbols for OpenJDK 11 on Debian or Ubuntu-based systems. These symbols are required for the allocation profiler mode in Spark.

```bash
apt install openjdk-11-dbg
```

--------------------------------

### Install libstdc++ for Alpine Linux

Source: https://spark.lucko.me/docs/misc/Using-async-profiler

Installs the libstdc++ library on Alpine Linux, which is a dependency for async-profiler. This command is typically run within a container or on a Linux system.

```bash
apk add libstdc++
```

--------------------------------

### Install libstdc++ for Debian/Ubuntu

Source: https://spark.lucko.me/docs/misc/Using-async-profiler

Installs the libstdc++6 package on Debian or Ubuntu-based systems. This is necessary for async-profiler if the library is not found.

```bash
aptinstall libstdc++6
```

--------------------------------

### Paper 1.21+ Bundled Spark Override

Source: https://spark.lucko.me/docs/Installation

For Paper 1.21 and newer, spark is bundled. To use a separate plugin version, append -Dpaper.preferSparkPlugin=true to server startup arguments. Refer to Paper documentation for details.

```bash
java -jar paper.jar -Dpaper.preferSparkPlugin=true
```

--------------------------------

### Navigating the Profile Tree

Source: https://spark.lucko.me/docs/Using-the-viewer

Explains how to expand nodes in the profiler viewer to explore the call stack and identify performance bottlenecks. It uses examples like 'Server thread', 'MinecraftServer.run()', and 'MinecraftServer.tick()'.

```English
Clicking on a node expands its children.
Example:
Server thread -> java.lang.Thread.run() -> MinecraftServer.run() -> MinecraftServer.tick()
```

--------------------------------

### Spark Agent Arguments

Source: https://spark.lucko.me/docs/Standalone-Agent

Specifies arguments for the Spark agent when attaching. Arguments like `port`, `start`, and `open` can be configured. Multiple arguments are separated by commas.

```APIDOC
Agent Arguments:

  port={port}
    - The port the agent should listen on. Default is `2222`.

  start
    - If present, the agent will start profiling immediately after attaching.

  open
    - If present, a link to the viewer will be printed to the console/logs after attaching.

Example Usage:
  java -javaagent:spark-x.y.z-standalone-agent.jar=port=2222,start,open -jar application.jar
```

--------------------------------

### Spark Profiler Commands

Source: https://spark.lucko.me/docs/Command-Usage

Commands to control and configure the Spark profiler. This includes starting, stopping, checking status, and customizing profiling behavior with various flags for execution and allocation profiling.

```APIDOC
Spark Profiler Commands:

Basic Usage:
  /spark profiler start
    - Starts the profiler in the default operation mode.
  /spark profiler open
    - Opens the profiler viewer page without stopping a running profiler.
  /spark profiler stop
    - Stops the profiler and prepares results for viewing.
  /spark profiler cancel
    - Cancels the profiler stop process without uploading results.
  /spark profiler info
    - Checks the current status of the profiler.

Execution Profiler Options:
  /spark profiler start --timeout <seconds>
    - Starts the profiler and automatically stops it after the specified duration.
  /spark profiler start --thread *
    - Starts the profiler and tracks all threads.
  /spark profiler start --thread <thread name>
    - Starts the profiler and tracks only specific threads.
  /spark profiler start --thread <thread name pattern> --regex
    - Starts the profiler and tracks threads matching the given regex pattern.
  /spark profiler start --interval <milliseconds>
    - Starts the profiler and samples at the specified interval (default: 4ms).
  /spark profiler start --only-ticks-over <milliseconds>
    - Starts the profiler, recording samples only from ticks exceeding the specified duration.
  /spark profiler start --combine-all
    - Starts the profiler, combining all threads under a single root node.
  /spark profiler start --not-combined
    - Starts the profiler, disabling the grouping of threads from a thread pool.
  /spark profiler start --ignore-sleeping
    - Starts the profiler, recording samples only from threads that are not in a 'sleeping' state.
  /spark profiler start --force-java-sampler
    - Starts the profiler, forcing the use of the Java sampler instead of the async sampler.
  /spark profiler stop --comment <comment>
    - Stops the profiler and includes the specified comment in the viewer.
  /spark profiler stop --save-to-file
    - Stops the profiler and saves the profile to a file in the config directory instead of uploading it.

Allocation Profiler Options:
  /spark profiler start --alloc
    - Starts the profiler to profile memory allocations (memory pressure).
  /spark profiler start --alloc --alloc-live-only
    - Starts the memory allocation profiler, retaining stats only for objects not garbage collected by the end of the profile.
  /spark profiler start --alloc --interval <bytes>
    - Starts the memory allocation profiler and samples at the specified rate in bytes (default: 524287 bytes / 512 KB).
```

--------------------------------

### Attach Spark Agent at Startup

Source: https://spark.lucko.me/docs/Standalone-Agent

This command demonstrates how to attach the spark standalone agent to a Java application when starting it. The `-javaagent` argument specifies the path to the agent JAR file. The `application.jar` is the main application to be run, followed by any application-specific arguments.

```java
java -javaagent:spark-x.y.z-standalone-agent.jar -jar application.jar [application args]
```

--------------------------------

### spark CPU Profiler vs. WarmRoast

Source: https://spark.lucko.me/docs/misc/spark-vs-others

Details the improvements and differences of spark's CPU profiler compared to its base, WarmRoast. It covers ease of installation, usage, output sharing, deobfuscation, optimization, and customization options.

```markdown
spark's CPU Profiler vs others

WarmRoast
Whilst the CPU profiler in spark is based on WarmRoast, it has been improved over time and differs from upstream in the following ways:
  * Installation and usage is significantly easier.
    * Access to the underlying server machine is not needed.
    * No need to expose/navigate to a temporary web server (open ports, disable firewall?, go to temp webpage)
  * Profiling output can be quickly viewed & shared with others.
  * Deobfuscation mappings can be applied without extra setup, and CraftBukkit and Fabric sources are supported in addition to MCP (Searge) names.
  * Sampler & viewer components have both been significantly optimized.
    * Now able to sample at a higher rate & use less memory doing so
  * Additional customisation options added.
    * Ability to filter output by "laggy ticks" only, group threads from thread pools together, etc
    * Ability to filter output to parts of the call tree containing specific methods or classes
  * Sampling accuracy improved
    * The profiler groups by distinct methods, and not just by method name
```

--------------------------------

### Accessing Spark API via SparkProvider

Source: https://spark.lucko.me/docs/Developer-API

This Java code shows the universal method to get the Spark API instance using the SparkProvider singleton, which works across all platforms.

```java
Spark spark = SparkProvider.get();
```

--------------------------------

### Tick Loop Timing Example (Normal)

Source: https://spark.lucko.me/docs/guides/The-tick-loop

Illustrates a scenario where server ticks complete within the 50ms limit, with the server sleeping for the remaining time to maintain a consistent tick rate.

```text
Tick 1: 15ms execution + 35ms sleep = 50ms total
Tick 2: 10ms execution + 40ms sleep = 50ms total
Tick 3: 20ms execution + 30ms sleep = 50ms total
```

--------------------------------

### Get Raw Spark Data (Sampler/Heap)

Source: https://spark.lucko.me/docs/misc/Raw-spark-data

Retrieves the actual raw sampler or heap data for a spark session from the user content endpoint. The Content-Type header indicates the data format (e.g., application/x-spark-sampler).

```HTTP
GET https://spark-usercontent.lucko.me/abc123
```

--------------------------------

### Containers and Docker Metric Issues

Source: https://spark.lucko.me/docs/misc/About-spark-metrics

Explains potential misreporting of metrics (CPU/Memory Usage) when running spark within containers like Pterodactyl. It clarifies that spark relies on standard Java and OS APIs, and issues are likely due to setup or underlying bugs.

```APIDOC
### Containers and Docker[](https://spark.lucko.me/docs/misc/About-spark-metrics#containers-and-docker "Direct link to Containers and Docker")
Occasionally, we see some metrics (mostly CPU/Memory Usage) being misreported when the server (and by extension spark) is running inside a container (Pterodactyl, etc.).
There's not much spark can do about this. As you can see above, spark just uses the standard Java and OS APIs to obtain raw metrics data. If it's not accurate, then this is either a problem with your setup or a Java/Docker/OS bug.
```

--------------------------------

### Get GC Activity

Source: https://spark.lucko.me/docs/Developer-API

Retrieves information about Garbage Collection (GC) activity since the server started. It returns a map of GarbageCollector objects, each providing details like name, average frequency, and average time.

```java
// Retrieve the GC activity since the server started
Map<String,GarbageCollector> gc = spark.gc();

for(GarbageCollector collector : gc.values()){
String name = collector.name();
long frequency = collector.avgFrequency();
double time = collector.avgTime();
}
```

--------------------------------

### Spark Profiler Command Usage

Source: https://spark.lucko.me/docs/Using-the-viewer

Details on how to use the `/spark profiler` command to generate and upload performance profiles for analysis in the viewer.

```APIDOC
Command: /spark profiler
Description: Generates and uploads a performance profile.
Usage: After running this command, a link will be provided to access the profile in the spark viewer.
Purpose: To capture performance data for detailed analysis.
```

--------------------------------

### Bookmarking Method Calls

Source: https://spark.lucko.me/docs/Using-the-viewer

Describes how to bookmark method calls for later reference or sharing. Bookmarking can be done by holding 'alt' and clicking, or by right-clicking and selecting 'Toggle bookmark'. Bookmarked methods are highlighted red and encoded in the URL.

```English
Hold ALT + Click or Right-click -> Toggle bookmark.
Bookmarked methods are highlighted red and encoded in the URL for sharing.
```

--------------------------------

### disableResponseBroadcast Configuration Example

Source: https://spark.lucko.me/docs/Configuration

This JSON snippet demonstrates how to configure the `disableResponseBroadcast` option. When set to `true`, Spark will not broadcast command output to online administrators. The default value is `false`.

```json
{
  "disableResponseBroadcast": false
}
```

--------------------------------

### Get CPU Usage Statistic

Source: https://spark.lucko.me/docs/Developer-API

Retrieves the CPU Usage statistic for the system. It allows polling for the average CPU usage percentage over specified time windows.

```java
// Get the CPU Usage statistic
DoubleStatistic<StatisticWindow.CpuUsage> cpuUsage = spark.cpuSystem();

// Retrieve the average usage percent in the last minute
double usageLastMin = cpuUsage.poll(StatisticWindow.CpuUsage.MINUTES_1);
```

--------------------------------

### Get TPS Statistic

Source: https://spark.lucko.me/docs/Developer-API

Retrieves the Ticks Per Second (TPS) statistic. This can be null on platforms that do not support ticks. It allows polling for average TPS over different time windows.

```java
// Get the TPS statistic (will be null on platforms that don't have ticks!)
DoubleStatistic<StatisticWindow.TicksPerSecond> tps = spark.tps();

// Retrieve the average TPS in the last 10 seconds / 5 minutes
double tpsLast10Secs = tps.poll(StatisticWindow.TicksPerSecond.SECONDS_10);
double tpsLast5Mins = tps.poll(StatisticWindow.TicksPerSecond.MINUTES_5);
```

--------------------------------

### Spark Activity Command

Source: https://spark.lucko.me/docs/Command-Usage

Prints information about recent activity performed by Spark. Requires the 'spark' or 'spark.activity' permission. Supports pagination using the --page argument.

```APIDOC
/spark activity [--page <page no>]
  Prints information about recent activity performed by spark.
  Requires the permission spark or spark.activity.
  Parameters:
    --page <page no>: View a specific page of activity.
```

--------------------------------

### Accessing Spark API on Bukkit

Source: https://spark.lucko.me/docs/Developer-API

This Java code demonstrates how to obtain an instance of the Spark API on a Bukkit platform using the RegisteredServiceProvider.

```java
RegisteredServiceProvider<Spark> provider = Bukkit.getServicesManager().getRegistration(Spark.class);
if(provider != null){
    Spark spark = provider.getProvider();

}
```

--------------------------------

### Get MSPT Statistic

Source: https://spark.lucko.me/docs/Developer-API

Retrieves the Milliseconds Per Tick (MSPT) statistic, representing tick duration. This can be null on platforms that do not support measurement. It allows polling for average MSPT values.

```java
// Get the MSPT statistic (will be null on platforms that don't support measurement!)
GenericStatistic<DoubleAverageInfo,StatisticWindow.MillisPerTick> mspt = spark.mspt();

// Retrieve the averages in the last minute
DoubleAverageInfo msptLastMin = mspt.poll(StatisticWindow.MillisPerTick.MINUTES_1);
double msptMean = msptLastMin.mean();
double mspt95Percentile = msptLastMin.percentile95th();
```

--------------------------------

### Spark TPS and CPU Usage

Source: https://spark.lucko.me/docs/Command-Usage

Prints information about the server's TPS (ticks per second) rate and CPU usage.

```APIDOC
/spark tps
  Description: Prints information about the server's TPS rate and CPU usage.
  Permissions: spark, spark.tps
```

--------------------------------

### Spark Heap Dump Summary

Source: https://spark.lucko.me/docs/Command-Usage

Generates a new memory (heap) dump summary and uploads it to the viewer. Optionally suggests running garbage collection before the summary is generated (deprecated).

```APIDOC
/spark heapsummary
  Description: Generates a new memory (heap) dump summary and uploads it to the viewer.
  Permissions: spark, spark.heapsummary
  Options:
    --run-gc-before: Suggests that the JVM runs the garbage collector before the heap summary is generated. (_deprecated_)
```

--------------------------------

### Tick Loop Timing Example (Lagging)

Source: https://spark.lucko.me/docs/guides/The-tick-loop

Demonstrates how a tick exceeding the 50ms limit causes subsequent ticks to be delayed, resulting in fewer ticks per second (lower TPS) and higher milliseconds per tick (MSPT).

```text
Tick 1: 15ms execution
Tick 2: 80ms execution (exceeds 50ms limit)
Tick 3: 70ms execution (delayed due to Tick 2)
Tick 4: 60ms execution (delayed due to Tick 3)
```

--------------------------------

### Spark Profiler Command

Source: https://spark.lucko.me/docs/Command-Usage

Provides access to the Spark profiler functionality.

```APIDOC
/spark profiler
  Accesses the Spark profiler.
```

--------------------------------

### spark-viewer UI Basis

Source: https://spark.lucko.me/docs/misc/Credits

Explains that the spark-viewer user interface is based on the original WarmRoast UI, with significant improvements including a re-write using the React framework.

```markdown
The spark-viewer user interface is based on the original WarmRoast UI, with a number of changes and improvements made over the years. The most significant of which was a re-write using the React framework, contributed by [astei](https://github.com/astei/.).
```

--------------------------------

### Applying Deobfuscation Mappings

Source: https://spark.lucko.me/docs/Using-the-viewer

Explains that the viewer automatically applies deobfuscation mappings to make method and class names understandable. If automatic detection fails, users can manually select mappings from a dropdown menu in the top right.

```English
Viewer automatically detects and applies deobfuscation mappings.
Manual selection available via dropdown in the top right.
```

--------------------------------

### Attach Spark Agent at Startup with Custom Port

Source: https://spark.lucko.me/docs/Standalone-Agent

This command shows how to attach the spark standalone agent and specify a custom port for communication. The `port` argument is appended to the agent JAR path, separated by an equals sign.

```java
java -javaagent:spark-x.y.z-standalone-agent.jar=port=2222-jar application.jar [application args]
```

--------------------------------

### Get Raw Spark Metadata (JSON)

Source: https://spark.lucko.me/docs/misc/Raw-spark-data

Fetches raw metadata for a spark session by appending '?raw=1' to the session URL. The response is in JSON format. Supports JSONPath filtering via '&path=' parameter and fetching all data with '&full=true'.

```HTTP
GET https://spark.lucko.me/abc123?raw=1
```

```HTTP
GET https://spark.lucko.me/abc123?raw=1&path=metadata.platform
```

```HTTP
GET https://spark.lucko.me/abc123?raw=1&full=true
```

--------------------------------

### Spark Garbage Collection History

Source: https://spark.lucko.me/docs/Command-Usage

Prints information about the server's GC (garbage collection) history.

```APIDOC
/spark gc
  Description: Prints information about the server's GC history.
  Permissions: spark, spark.gc
```

--------------------------------

### Viewer URL Configuration

Source: https://spark.lucko.me/docs/Configuration

Configures the URL used for linking to the spark viewer in command outputs. This URL should end with a '/'. The default is 'https://spark.lucko.me/'.

```json
{
  "viewerUrl":"https://spark.lucko.me/"
}
```

--------------------------------

### Flame Graph Interaction

Source: https://spark.lucko.me/docs/Using-the-viewer

Details how to interact with the Flame Graph visualization in the Spark profiler. This includes opening the view, understanding node width, focusing on nodes, hovering for details, and exiting the view.

```markdown
To open the flame view, either click on the Flame icon in the top controls bar, or **right-click** on a thread/method call and select "**View as Flame Graph** ".

The **width** of each node in this view **corresponds** to the portion of time spent executing it.

You can **click** on a node to "**focus** " it, and expand it to fill the full width of the page. The child nodes beneath it will expand accordingly.

You can **hover** over a node to view the full method name & profiled time.

To **exit** the flame view and go back to the profiler tree, just click the "**Exit Flame View** " button in the **top right** of the page.
```

--------------------------------

### Profiler Tree Interpretation

Source: https://spark.lucko.me/docs/Using-the-viewer

Explains the components of the profiler tree displayed in the spark viewer, including threads, call frames, and info points.

```APIDOC
Profiler Tree Components:

1. Threads:
   - Represents workers performing tasks within the application (e.g., 'Server thread' in Minecraft).
   - Threads at the root of the profile display 100% time.

2. Call Frames ('nodes'):
   - Display the name of the class/method, percentage of time taken by the frame relative to its parent, and milliseconds (on hover).
   - Hovering over a node shows the predicted time spent executing it.

3. Info Points (ⓘ):
   - Symbols next to notable call frames providing extra information upon hovering.
   - Descriptions are community-contributed and can be improved via [contributing](https://spark.lucko.me/docs/misc/Info-points).
```

--------------------------------

### spark vs. Minecraft Timings

Source: https://spark.lucko.me/docs/misc/spark-vs-others

Compares spark's data collection and analysis features with Minecraft Timings. It outlines what Timings can do that spark cannot, and vice versa, focusing on the level of detail and ease of use for different user needs.

```markdown
Minecraft Timings
Aikar's [timings](https://github.com/aikar/timings) system (built into Spigot and Sponge) is similar to spark in the sense that it also records data about server performance and presents this for analysis.
Timings can do the following things that spark does not:
  * Count the number of times certain things (events, entity ticking, etc.) occur within the recorded period
  * Display output in a way that is more easily understandable by server admins unfamiliar with reading profiler data
  * Break down server activity by "friendly" descriptions of the nature of the work being performed

If these things are important to you, then timings is likely a better option.
However, if they are less important, then spark has a few advantages:
  * Each area of analysis does not need to be manually defined - spark will record data for everything.
    * 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 will.
  * For programmers interested in optimizing plugins or the server software (or server admins wishing to report issues), the spark output is usually more useful.
    * Timings is not detailed enough to give information about slow areas of code.
```

--------------------------------

### Spark Heap Dump Generation

Source: https://spark.lucko.me/docs/Command-Usage

Generates a new heapdump (.hprof snapshot) file and saves it to disk. Supports compression and inclusion of non-live objects (deprecated).

```APIDOC
/spark heapdump
  Description: Generates a new heapdump (.hprof snapshot) file and saves it to the disk.
  Permissions: spark, spark.heapdump
  Options:
    --compress <type>: Specify compression type (gzip, xz, lzma).
    --include-non-live: Specify inclusion of "non-live" objects. (_deprecated_)
    --run-gc-before: Suggests that the JVM runs the garbage collector before the heap dump is generated. (_deprecated_)
```

--------------------------------

### Spark Memory Management Commands

Source: https://spark.lucko.me/docs/Command-Usage

Commands related to garbage collection and memory analysis in Spark.

```APIDOC
/spark gc
  Triggers a garbage collection cycle.

/spark gcmonitor
  Monitors garbage collection activity.

/spark heapsummary
  Displays a summary of the heap memory.

/spark heapdump
  Generates a heap dump for memory analysis.
```

--------------------------------

### Method Description Format

Source: https://spark.lucko.me/docs/misc/Info-points

Defines the structure for providing descriptions for specific methods within the spark viewer. The 'method' key specifies the fully qualified method name, and the 'description' key contains the Markdown-formatted text to be displayed.

```yaml
-method: net.minecraft.network.protocol.PlayerConnectionUtils.run()
  description:>
    Manages player (client) connections to the server, in particular the processing of incoming
    packets (actions performed by players).

```

--------------------------------

### Bytebin URL Configuration

Source: https://spark.lucko.me/docs/Configuration

Sets the URL for the bytebin instance used for uploading profiles and heap dump summaries. The URL must end with a '/'. The default is 'https://spark-usercontent.lucko.me/'.

```json
{
  "bytebinUrl":"https://spark-usercontent.lucko.me/"
}
```

--------------------------------

### Spark Profiler Overview

Source: https://spark.lucko.me/docs/misc/spark-vs-others

Provides a general overview of the Spark profiler, its characteristics as a sampling profiler, and its advantages over other methods like instrumentation. It also mentions the ease of applying deobfuscation mappings and its suitability for most Minecraft server performance issues.

```Java
/*
 * Spark (a sampling profiler) is typically less numerically accurate compared to other profiling methods (e.g. instrumentation), 
 * but allows the target program to run at near full speed.
 * 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.
 * 
 * With spark it is not necessary to inject a Java agent when starting the server.
 * Easy to apply deobfuscation mappings.
 * spark is more than good enough for the vast majority of performance issues likely to be encountered on Minecraft servers, 
 * but may fall short when analysing performance of code ahead of time (in other words before it becomes a bottleneck / issue).
 */

```

--------------------------------

### Spark Placeholders for PlaceholderAPI/MVdWPlaceholderAPI

Source: https://spark.lucko.me/docs/misc/Placeholders

Provides a list of placeholders for displaying server performance metrics. These placeholders can be integrated with PlaceholderAPI and MVdWPlaceholderAPI to show real-time data such as TPS, tick duration, and CPU usage in-game.

```APIDOC
Spark Placeholders:

%spark_tps%
  Description: Returns a formatted summary of the average TPS in the last 5s, 10s, 1m, 5m and 15m.

%spark_tps_5s%
  Description: Returns a formatted representation of the average TPS in the last 5 seconds.

%spark_tps_10s%
  Description: Returns a formatted representation of the average TPS in the last 10 seconds.

%spark_tps_1m%
  Description: Returns a formatted representation of the average TPS in the last minute.

%spark_tps_5m%
  Description: Returns a formatted representation of the average TPS in the last 5 minutes.

%spark_tps_15m%
  Description: Returns a formatted representation of the average TPS in the last 15 minutes.

%spark_tickduration%
  Description: Returns a formatted summary of the average tick durations in the last 10 seconds and 1 minute.

%spark_tickduration_10s%
  Description: Returns a formatted representation of the average tick duration in the last 10 seconds.

%spark_tickduration_1m%
  Description: Returns a formatted representation of the average tick duration in the last minute.

%spark_cpu_system%
  Description: Returns a formatted summary of the average CPU usage (system) in the last 10 seconds, 1 minute and 15 minutes.

%spark_cpu_system_10s%
  Description: Returns a formatted representation of the average CPU usage (system) in the last 10 seconds.

%spark_cpu_system_1m%
  Description: Returns a formatted representation of the average CPU usage (system) in the last minute.

%spark_cpu_system_15m%
  Description: Returns a formatted representation of the average CPU usage (system) in the last 15 minutes.

%spark_cpu_process%
  Description: Returns a formatted summary of the average CPU usage (process) in the last 10 seconds, 1 minute and 15 minutes.

%spark_cpu_process_10s%
  Description: Returns a formatted representation of the average CPU usage (process) in the last 10 seconds.

%spark_cpu_process_1m%
  Description: Returns a formatted representation of the average CPU usage (process) in the last minute.

%spark_cpu_process_15m%
  Description: Returns a formatted representation of the average CPU usage (process) in the last 15 minutes.
```

--------------------------------

### Profiler Viewer Views

Source: https://spark.lucko.me/docs/Using-the-viewer

Outlines the different views supported by the profiler viewer, which can be toggled using the '👁️' button. The 'All View' is the default, displaying the entire profile as an expandable tree.

```English
Toggle views using the '👁️' button.
Default view: All View (expandable tree).
```

--------------------------------

### Sources View Merge Modes

Source: https://spark.lucko.me/docs/Using-the-viewer

Explains the merge modes in the Sources View of the Spark profiler, which helps in identifying badly performing plugins or mods. Modes are 'Merge' and 'Separate'.

```markdown
Merge Mode | Description  
---|---
**Merge** | Method calls with the same signature will be merged together, even though they may not have been invoked by the same calling method.  
**Separate** | Method calls that have the same signature, but that haven't been invoked by the same calling method will show separately.
```

--------------------------------

### Spark Health Commands

Source: https://spark.lucko.me/docs/Command-Usage

Includes commands for checking the health and status of Spark.

```APIDOC
/spark health
  Checks the general health of Spark.

/spark ping
  Sends a ping to check connectivity.

/spark tps
  Displays transactions per second (TPS).

/spark tickmonitor
  Monitors Spark's tick system.
```

--------------------------------

### spark Profiler Engines

Source: https://spark.lucko.me/docs/misc/Credits

Describes the two profiler engines used by spark: the 'async' engine which is a wrapper around async-profiler, and the 'built-in java' engine which is an improved version of WarmRoast.

```markdown
The spark has two profiler "engines":
  * The `async` engine is a wrapper around [async-profiler](https://github.com/jvm-profiling-tools/async-profiler) by [apangin](https://github.com/apangin).
  * The `built-in java` engine is an improved version of the [WarmRoast](https://github.com/sk89q/WarmRoast) profiler by [sk89q](https://github.com/sk89q).
```

--------------------------------

### Add libstdc++ to Debian/Ubuntu Dockerfile

Source: https://spark.lucko.me/docs/misc/Using-async-profiler

Adds the libstdc++6 package to a Debian or Ubuntu-based Docker image. This is a common step when preparing a Docker environment for applications requiring this library, such as async-profiler.

```dockerfile
RUN apt-get install libstdc++6
```

--------------------------------

### Analyzing Performance with Percentages

Source: https://spark.lucko.me/docs/Using-the-viewer

Details how to use the percentage values displayed next to each node to identify areas consuming the most time. The process involves expanding nodes with relatively high percentages to pinpoint the cause of performance problems.

```English
Follow percentages to find problematic areas.
Example: WorldServer.doTick() (ticking world), WorldServer.tickEntities() (ticking entities), CraftScheduler.mainThreadHeartbeat() (plugin scheduler tasks)
```

--------------------------------

### Gradle (Groovy DSL) Dependency for Spark API

Source: https://spark.lucko.me/docs/Developer-API

This snippet demonstrates how to configure Gradle with the necessary repository and add the spark API as a compile-only dependency using Groovy DSL.

```groovy
repositories {
    maven {
        name 'luck-repo'
        url 'https://repo.lucko.me/'
        content {
            includeModule 'me.lucko','spark-api'
}
}
}

dependencies {
    compileOnly 'me.lucko:spark-api:0.1-SNAPSHOT'
}
```

--------------------------------

### spark Project Licenses

Source: https://spark.lucko.me/docs/misc/Credits

Details the open-source licenses under which the spark, spark-viewer, and spark-docs projects are released.

```markdown
spark is released under the terms of the [GNU GPLv3 license](https://github.com/lucko/spark/blob/master/LICENSE.txt).
  * spark-viewer is released under the terms of the [GNU GPLv3 license](https://github.com/lucko/spark-viewer/blob/master/LICENSE.txt).
  * spark-docs is released under the terms of the [CC-BY-SA-4.0 license](https://github.com/lucko/spark-docs/blob/master/LICENSE.txt).
```

--------------------------------

### spark Metrics Data Sources

Source: https://spark.lucko.me/docs/misc/About-spark-metrics

Details the metrics spark can report and their corresponding data sources. This includes server events, Java APIs, and OS-specific files.

```APIDOC
Metric Name | Data Source  
---|---
TPS | Server event (via spark's `TickHook` interface)  
MSPT | Server event (via spark's `TickReporter` interface)  
CPU Usage | Java API ([jdk.management/OperatingSystemMXBean](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html))  
Memory Usage | Java API ([jdk.management/OperatingSystemMXBean](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/OperatingSystemMXBean.html)) & `/proc/meminfo` (Linux only)  
Disk Usage | Java API ([java.base/FileStore](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/nio/file/FileStore.html))  
GC | Java API ([jdk.management/GarbageCollectorMXBean](https://docs.oracle.com/en/java/javase/17/docs/api/jdk.management/com/sun/management/GarbageCollectorMXBean.html))  
Network Usage |  `/proc/net/dev` (Linux only)  
Player Ping | Server API (via spark's `PlayerPingProvider` interface)  
CPU Name |  `/proc/cpuinfo` on Linux, `wmic cpu` on Windows  
OS name and version |  `/etc/os-release` on Linux, `wmic os` on Windows
```

--------------------------------

### Bytesocks Host Configuration

Source: https://spark.lucko.me/docs/Configuration

Defines the hostname for the bytesocks instance used for communication with the spark viewer. The default is 'spark-usersockets.lucko.me'.

```json
{
  "bytesocksHost":"spark-usersockets.lucko.me"
}
```

--------------------------------

### Background Profiler Engine Configuration

Source: https://spark.lucko.me/docs/Configuration

Specifies the engine for the background profiler. Supported values are 'async' (default) and 'java'.

```json
{
  "backgroundProfilerEngine":"async"
}
```

--------------------------------

### Spark Player Ping Information

Source: https://spark.lucko.me/docs/Command-Usage

Prints information about average or specific player ping round trip times. Allows viewing average pings across all players or a specific player's current ping.

```APIDOC
/spark ping
  Description: Prints information about average player ping round trip times.
  Permissions: spark, spark.ping

/spark ping --player <username>
  Description: Prints information about a specific player's current ping RTT.
  Parameters:
    username: The username of the player.
  Permissions: spark, spark.ping
```

--------------------------------

### CLI Tool for Parsing Raw Spark Data

Source: https://spark.lucko.me/docs/misc/Raw-spark-data

A simple Command Line Interface (CLI) tool written in Node.js that demonstrates how to parse raw spark data. This tool powers the JSON endpoint for spark metrics.

```Node.js
console.log("This is a placeholder for the Node.js CLI tool. The actual code can be found at https://github.com/lucko/spark2json");
// The actual implementation involves reading and parsing spark data, likely using protobuf definitions.
```

--------------------------------

### Add libstdc++ to Alpine Dockerfile

Source: https://spark.lucko.me/docs/misc/Using-async-profiler

Adds the libstdc++ package to an Alpine Linux-based Docker image during the build process. This ensures the dependency is available for async-profiler.

```dockerfile
RUN apk add --no-cache libstdc++
```

--------------------------------

### Grouping Multiple Method Descriptions

Source: https://spark.lucko.me/docs/misc/Info-points

Allows multiple methods to share a single description by using a plural 'methods' key followed by a list of method names. This simplifies the management of common descriptions across different methods.

```yaml
-methods:
- net.minecraft.server.MinecraftServer.waitUntilNextTick()
- net.minecraft.server.IAsyncTaskHandler.sleepForTick()
  description:>
    todo

```

--------------------------------

### Flat View Modes

Source: https://spark.lucko.me/docs/Using-the-viewer

Describes the display and sort modes available in the Flat View of the Spark profiler. Display modes include 'Top Down' and 'Bottom Up', while sort modes include 'Total Time' and 'Self Time'.

```markdown
Display Mode | Description  
---|---
**Top Down** | The call tree is "normal" - expanding a node reveals the sub-methods that it calls.  
**Bottom Up** | The call tree is reversed - expanding a node reveals the method that called it.  

Sort Mode | Description  
---|---
**Total Time** | Methods are sorted according to their "total time" (the time spent executing code within the method and the time spent executing sub-calls)  
**Self Time** | Methods are sorted according to their "self time" (the time spent executing code within the method)
```

--------------------------------

### Thread Description Format

Source: https://spark.lucko.me/docs/misc/Info-points

Defines the structure for providing descriptions for specific threads within the spark viewer. The 'thread' key specifies the thread name, and the 'description' key contains the Markdown-formatted text to be displayed.

```yaml
-thread: Server thread
  description:>
    The main server thread that the game loop is executed on. See the
    [Tick Loop guide](https://spark.lucko.me/docs/guides/The-tick-loop) for more info.

```

--------------------------------

### Spark Health Report

Source: https://spark.lucko.me/docs/Command-Usage

Generates a health report for the server, including TPS, CPU, Memory, and Disk Usage. Supports uploading the report and including detailed memory or network usage.

```APIDOC
/spark health
  Description: Generates a health report for the server.
  Permissions: spark, spark.healthreport
  Options:
    --upload: Upload the health report and return a shareable link.
    --memory: Include additional information about JVM memory usage.
    --network: Include additional information about system network usage.
```

--------------------------------

### Spark GC Monitor Control

Source: https://spark.lucko.me/docs/Command-Usage

Controls the GC (garbage collection) monitoring system. Can be toggled on and off.

```APIDOC
/spark gcmonitor
  Description: Toggles the GC monitoring system on and off.
  Permissions: spark, spark.gcmonitor
```

--------------------------------

### Spark Metrics for Lagging Server

Source: https://spark.lucko.me/docs/guides/The-tick-loop

Shows how spark would report metrics like TPS and MSPT for a server experiencing lag, based on the timing of tick executions.

```text
Reported TPS: 17
Reported MSPT: min ~20ms, max ~80ms
```
Tokens:
Raw