Timings

What is Timings?

Timings provide you useful information to tune your server's performance. In timings, provided by the server, such as Spigot, PaperSpigot, Sponge, etc., the info of TriggerReactor is arbitrary since TriggerReactor does not fully run on the server thread. /trg timings command is introduced in 3.0.0 to discover this hidden information. Simple descriptions can be found in Commands and Permissions.

How to interpret?

First of all, make sure that the timings are on using /trg timings toggle. If it is on, give some time so that enough information will be gathered to get some estimation about each working Triggers in your server.

Then, when you type /trg timings print, you will see output like below:

---

 > Root[1] -- (total: 10186ms, count: 102, avg: 99.86ms)
   > CommandTrigger[1] -- (total: 10186ms, count: 102, avg: 99.86ms)
     > temp[2] -- (total: 10186ms, count: 102, avg: 99.86ms)
       > Code Interpretation -- (total: 4982ms, count: 1, avg: 4982ms)
       > Executors[1] -- (total: 221ms, count: 100, avg: 2.21ms)
         > #MESSAGE -- (total: 221ms, count: 100, avg: 2.21ms)  !!MainThread

---

Pretty neat. Let's take a look at each component one by one.

Root[1] -- (total: 10186ms, count: 102, avg: 99.86ms)

This line will always show up since it holds the total execution time of the TriggerReactor plugin. But don't be fooled by the high average! Timings include both execution in Server and Dedicated TriggerReactor Thread, so the high number of execution time doesn't necessarily mean your server is suffering a performance issue.

Intuitively, the total is the sum of every execution that happened in Triggers in your server, the count is the number of the executions, and the avg is simply the total divided by count.

So in the above case, on average, TriggerReactor uses about 100ms of CPU time executing one or more Triggers about 100 times either in server thread or TriggerReactor thread or both.

The number next to the Root means how many children belong to this tree.

CommandTrigger[1] -- (total: 10186ms, count: 102, avg: 99.86ms)

temp[2] -- (total: 10186ms, count: 102, avg: 99.86ms)

The direct children of the Root are the types of Trigger, and because I have a CommandTrigger, named temp, it shows that information. Just as you expected, it means the CommandTrigger, temp, is pretty much only Trigger exists in my server.

Code Interpretation -- (total: 4982ms, count: 1, avg: 4982ms)

Each Trigger interprets the code, and Code Interpretation measures how much time it took to interpret the code. Again, don't be fooled by the number since it's a very simple measure. What it means by simple is that it records the [end time - start time] of the execution, so if the internal call wait for some execution to be done, the execution time also increases.

For example, because each call of the Executor and Placeholder takes 1 tick in Server Thread, TriggerReactor must wait for the Executor or Placeholder to finish its work and each tick takes about 50ms. So if there are 10 calls to Executor or Placeholder, the interpreter must wait for about 500ms! You will see why the number is so high blow.

Executors[1] -- (total: 221ms, count: 100, avg: 2.21ms)

Intuitively, it shows how much Executors were used in this Trigger. There was only 1 Executor, and it was called 100 times. Now, you can pretty much see why the Code Interpretation took about 50ms*100.

#MESSAGE -- (total: 221ms, count: 100, avg: 2.21ms) !!MainThread

This is the actual Executor used. So #MESSAGE was called 100 times, and on average, each call used 2.21ms of execution time.

Notice the !!MainThread. It lets you know that the execution took place in your server thread! So this is where you have to keep your eyes on since if it takes too much time executing something in the server thread too long, the server will eventually crash. Each server tick is 50ms, so if the sum of tasks run in your server thread is more than 50ms, the TPS will drop. However, even if it's over 50ms, it doesn't necessarily mean that it was caused by TriggerReactor. Since the server thread is single-threaded, every resource (Mobs, AI, Chunk generation, Packets, Plugins, etc.) must share this 50ms of execution time together.

Special Cases

There are some cases, where the execution time might seem sky-high, and one possible scenario is using InventoryTrigger.

For example, one of the possible applications of InventoryTrigger is using the multi-threading capability to make a real-time animation GUI, and we use the WHILE loop to do that. As I already mentioned, the timings are very simple measure, so it only records [end time - start time]. It means that as long as the GUI is open, and the WHILE loop is running, the 'end time` will keep increase indefinitely. So don't be fooled by this information.

---

That pretty much sums up everything. I hope this is useful to tune your server while using TriggerReactor!