Documentation

Executor Service Metrics

Thread Pools

A Thread Pool is represented by a instance of the class ExecutorService. Using an ExecutorService, you can submit a series of tasks that will be completed in the future.

Executors class provides some factory methods in order to create types of thread pools as following:

  • Single Thread Executor: A thread pool with only one thread.
  • Cached Thread Pool: A thread pool that create as many threads it needs to execute the task in parallel.
  • Fixed Thread Pool: A thread pool with a fixed number of threads.
  • Scheduled Thread Pool: A thread pool made to schedule future task.
  • Single Thread Scheduled Pool: A thread pool with only one thread to schedule future task.
  • Work Stealing Pool: Creates a work-stealing thread pool using all available processors as its target parallelism level.

Thread Pool Metrics

The metrics provided for each Thread Pool will change depending on the type of pool at hand. To know for sure what kind of pool you are looking at, we will always include a tag named executor-type whose value will always be present and be either fork-join-pool for thread-pool-executor, matching the type of thread pool that you actually created.

Fork Join Pool

When your pool type is fork-join-pool you will get:

  • parallelism: a min max counter with the desired parallelism value. This value will remain steady over time.
  • pool-size: a gauge tracking the number of worker threads that have started but not yet terminated. This value will differ that of parallelism if threads are created to maintain parallelism when others are cooperatively blocked.
  • active-threads: a gauge tracking an estimate of the number of threads that are currently stealing or executing tasks.
  • running-threads: a gauge tracking an estimate of the number of worker threads that are not blocked waiting to join tasks or for other managed synchronization.
  • queued-task-count: a gauge tracking the total number of tasks currently held in queues by worker threads (but not including tasks submitted to the pool that have not begun executing). This value is only an approximation, obtained by iterating across all threads in the pool.

Thread Pool Executor

When your pool type is thread-pool-executor you will get:

  • core-pool-size: a gauge tracking the core pool size of the executor.
  • max-pool-size: a gauge tracking the maximum number of threads allowed by the executor.
  • pool-size: a gauge tracking the current number of threads in the pool.
  • active-threads: a gauge tracking the number of threads that are actively executing tasks.
  • processed-tasks: a gauge tracking the number of processed tasks for the executor. Please not that even while the ThreadPoolExecutor provides us with the total number of tasks ever processed by the executor, this metrics is effectively tracking the number of tasks as a differential from the last recorded value.

Thread Pools are very important to execute synchronous and asynchronous processes in our applications and for that reason Kamon provides a simple way to monitoring them.

val forkJoinPool = Executors.newWorkStealingPool()
val fixedThreadPool = Executors.newFixedThreadPool(10)

val forkJoinEntity = ExecutorServiceMetrics.register("java-fork-join-pool", forkJoinPool)
val threadPoolEntity = ExecutorServiceMetrics.register("fixed-thread-pool", fixedThreadPool)

for (_ <- 0 to 100) {
  forkJoinPool.submit(HeavyWeightTask())
  fixedThreadPool.submit(HeavyWeightTask())
}

ExecutorServiceMetrics.remove(forkJoinEntity)
ExecutorServiceMetrics.remove(threadPoolEntity)

forkJoinPool.shutdown()
fixedThreadPool.shutdown()
final ExecutorService forkJoinPool = Executors.newWorkStealingPool();
final ExecutorService fixedThreadPool = Executors.newFixedThreadPool(10);

final Entity forkJoinEntity = ExecutorServiceMetrics.register("fork-join-pool", forkJoinPool);
final Entity threadPoolEntity = ExecutorServiceMetrics.register("fixed-thread-pool", fixedThreadPool);

for(int i = 0; i < 100; i++) {
    forkJoinPool.submit(new HeavyWeightTask());
    fixedThreadPool.submit(new HeavyWeightTask());
}

ExecutorServiceMetrics.remove(forkJoinEntity);
ExecutorServiceMetrics.remove(threadPoolEntity);

forkJoinPool.shutdown();
fixedThreadPool.shutdown();

The output for example above using the kamon-log-reporter module should be like the following:

+------------------------------------------------------------------------------------------------+
|  Thread-Pool-Executor                                                                          |
|                                                                                                |
|  Name: fixed-thread-pool                                                                       |
|                                                                                                |
|  Core Pool Size: 10                                                                            |
|  Max  Pool Size: 10                                                                            |
|                                                                                                |
|                                                                                                |
|                         Pool Size        Active Threads          Processed Task                |
|           Min              10                  0                      0                        |
|           Avg              10.0                1.0                    0.0                      |
|           Max              10                  10                     0                        |
|                                                                                                |
+------------------------------------------------------------------------------------------------+

+------------------------------------------------------------------------------------------------+
|  Fork-Join-Pool                                                                                |
|                                                                                                |
|  Name: fork-join-pool                                                                          |
|                                                                                                |
|  Paralellism: 4                                                                                |
|                                                                                                |
|                 Pool Size       Active Threads     Running Threads     Queue Task Count        |
|      Min           2                 0                   0                   0                 |
|      Avg           3.0               0.0                 1.0                 0.0               |
|      Max           4                 0                   4                   0                 |
|                                                                                                |
+------------------------------------------------------------------------------------------------+