Executor Service Instrumentation #

This module lets you collect metrics from an Executor Service, be it a Thread Pool Executor or a Fork Join Pool. To start tracking an Executor Service you will need to register it with the executors module by calling ExecutorsInstrumentation.instrument(...) as shown below:

Registering a Executor Service

  val executor = java.util.concurrent.Executors.newFixedThreadPool(10)
  val instrumented = ExecutorInstrumentation.instrument(executor, "sample-executor")

  // Form this point on, submit tasks to the "instrumented" executor.

You will get back an instrumented Executor Service that will be recording metrics until it is shut down. It is important to ensure that the instrumented executor is being used and not the original one, otherwise some metrics and Context propagation features will not work as expected.

Options #

When instrumenting an Executor Service you have the possibility to tweak two different options:

Tracking time in queue (default: yes) will track setup a timer that measures the time between submitting a task to the executor and when it starts executing.
Propagate Context on submit (default: no) will capture the current Context at the moment a task is submitted to the executor and restore that Context when the task gets executed. In most cases you will not need to enable this option because the bytecode instrumentation shipping on this module will take care of performing Context propagation, but if you are doing manual instrumentation, this will definitely be useful for you.

Collected Metrics #

The following metrics are collected for both ThreadPoolExecutor and ForkJoinPool:

executor.threads.min gauge

Tracks executor minimum number of Threads.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

executor.threads.max gauge

Tracks executor maximum number of Threads.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

executor.threads.active histogram

Samples the number of active threads on the executor service.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

executor.threads.total histogram

Samples the total number of threads on the executor service.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

executor.tasks.completed counter

Tracks the number of tasks that completed execution on the executor service.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

executor.tasks.submitted counter

Tracks the number of tasks submitted to the executor service.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

executor.time-in-queue timer

Tracks the time that tasks spend on the executor service's queue.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

executor.queue-size histogram

Samples the number of tasks queued for execution on the executor service.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

Additionally, the parallelism setting is also reported for ForkJoinPool executors:

executor.parallelism gauge

Tracks executor parallelism. This metrics is only available for ForkJoinPool executors.

Tags included by default:

name: The name assigned to the Executor.
type: Either "fjp" for ForkJoinPool executors or "tpe" for ThreadPoolExecutors.

Manual Installation #

In case you are not using the Kamon Bundle, add the dependency below to your build to instrument Akka 2.4 and Akka 2.5 applications.


libraryDependencies += "io.kamon" %% "kamon-executors" % "2.5.9"


    <dependency>
      <groupId>io.kamon</groupId>
      <artifactId>kamon-executors_2.13</artifactId>
      <version>2.5.9</version>
    </dependency>


implementation 'io.kamon:kamon-executors_2.13:2.5.9'

You must start your application with the instrumentation agent for this module to work properly.

On this article