Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

statsd-jvm-profiler

Simple JVM Profiler Using StatsD and Other Metrics Backends

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402 (1 ratings)
Rated 5.0 out of 5
Subscribe to updates I use statsd-jvm-profiler


Statistics on statsd-jvm-profiler

Number of watchers on Github 264
Number of open issues 2
Average time to close an issue 27 days
Main language Java
Average time to merge a PR about 7 hours
Open pull requests 0+
Closed pull requests 1+
Last commit about 3 years ago
Repo Created almost 5 years ago
Repo Last Updated over 1 year ago
Size 1.05 MB
Organization / Authoretsy
Latest Release2.1.0
Contributors5
Page Updated
Do you use statsd-jvm-profiler? Leave a review!
View open issues (2)
View statsd-jvm-profiler activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating statsd-jvm-profiler for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)
What people are saying about statsd-jvm-profiler Leave a review
Make my profiling work easy specially on hadoop world !!!

statsd-jvm-profiler Build Status

statsd-jvm-profiler is a JVM agent profiler that sends profiling data to StatsD. Inspired by riemann-jvm-profiler, it was primarily built for profiling Hadoop jobs, but can be used with any JVM process.

Read the blog post that introduced statsd-jvm-profiler on Code as Craft, Etsy's engineering blog.

Also check out the blog post reflecting on the experience of open-sourcing the project.

Mailing List

There is a mailing list for this project at https://groups.google.com/forum/#!forum/statsd-jvm-profiler. If you have questions or suggestions for the project send them here!

Installation

You will need the statsd-jvm-profiler JAR on the machine where the JVM will be running. If you are profiling Hadoop jobs, that means the JAR will need to be on all of the datanodes.

The JAR can be built with mvn package. You will need a relatively recent Maven (at least Maven 3).

statsd-jvm-profiler is available in Maven Central:

<dependency>
  <groupId>com.etsy</groupId>
  <artifactId>statsd-jvm-profiler</artifactId>
  <version>2.0.0</version>
</dependency>

If you would like an uberjar containing all of the dependencies instead of the standard JAR, use the jar-with-dependencies classifier:

<dependency>
  <groupId>com.etsy</groupId>
  <artifactId>statsd-jvm-profiler</artifactId>
  <version>2.0.0</version>
  <classifier>jar-with-dependencies</classifier>
</dependency>

Usage

The profiler is enabled using the JVM's -javaagent argument. You are required to specify at least the StatsD host and port number to use. You can also specify the prefix for metrics and a whitelist of packages to be included in the CPU profiling. Arguments can be specified like so:

-javaagent:/usr/etsy/statsd-jvm-profiler/statsd-jvm-profiler.jar=server=hostname,port=num

You should use the uberjar when starting the profiler in this manner so that all the profiler's dependencies are available.

The profiler can also be loaded dynamically (after the JVM has already started), but this technique requires relying on Sun's tools.jar, meaning it's an implementation-specific solution that might not work for all JVMs. For more information see the Dynamic Loading section.

An example of setting up Cascading/Scalding jobs to use the profiler can be found in the example directory.

Global Options

Name Meaning
server The hostname to which the reporter should send data (required)
port The port number for the server to which the reporter should send data (required)
prefix The prefix for metrics (optional, defaults to statsd-jvm-profiler)
packageWhitelist Colon-delimited whitelist for packages to include (optional, defaults to include everything)
packageBlacklist Colon-delimited whitelist for packages to exclude (optional, defaults to exclude nothing)
profilers Colon-delimited list of profiler class names (optional, defaults to CPUTracingProfiler and MemoryProfiler)
reporter Class name of the reporter to use (optional, defaults to StatsDReporter)
httpServerEnabled Determines if the embedded HTTP server should be started. (optional, defaults to true)
httpPort The port on which to bind the embedded HTTP server (optional, defaults to 5005). If this port is already in use, the next free port will be taken.

Embedded HTTP Server

statsd-jvm-profiler embeds an HTTP server to support simple interactions with the profiler while it is in operation. You can configure the port on which this server runs with the httpPort option. You can disable it altogether using the httpServerEnabled=false argument.

Endpoint Usage
/profilers List the currently enabled profilers
/isRunning List the running profilers. This should be the same as /profilers.
/disable/:profiler Disable the profiler specified by :profiler. The name must match what is returned by /profilers.
/errors List the past 10 errors from the running profilers and reporters.
/status/profiler/:profiler Displays a status message with the number of recorded stats for the requested profiler.

Reporters

statsd-jvm-profiler supports multiple backends. StatsD is the default, but InfluxDB is also supported. You can select the backend to use by passing the reporter argument to the profiler; StatsDReporter and InfluxDBReporter are the supported values.

Some reporters may require additional arguments.

StatsDReporter

This reporter does not have any additional arguments.

InfluxDBReporter

Name Meaning
username The username with which to connect to InfluxDB (required)
password The password with which to connect to InfluxDB (required)
database The database to which to write metrics (required)
tagMapping A mapping of tag names from the metric prefix (optional, defaults to no mapping)
Tag Mapping

InfluxDB 0.9 supports tagging measurements and querying based on those tags. statsd-jvm-profilers uses these tags to support richer querying of the produced data. For compatibility with other metric backends, the tags are extracted from the metric prefix.

If the tagMapping argument is not defined, only the prefix tag will be added, with the value of the entire prefix.

tagMapping should be a period-delimited set of tag names. It must have the same number of components as prefix, or else an exception would be thrown. Each component of tagMapping is the name of the tag. The component in the corresponding position of prefix will be the value.

If you do not want to include a component of prefix as a tag, use the special name SKIP in tagMapping for that position.

Profilers

statsd-jvm-profiler offers 3 profilers: MemoryProfiler, CPUTracingProfiler and CPULoadProfiler.

The metrics for all these profilers will prefixed with the value from the prefix argument or it's default value: statsd-jvm-profiler.

You can enable specific profilers through the profilers argument like so:

  1. Memory metrics only: profilers=MemoryProfiler
  2. CPU Tracing metrics only: profilers=CPUTracingProfiler
  3. JVM/System CPU load metrics only: profilers=CPULoadProfiler

Default value: profilers=MemoryProfiler:CPUTracingProfiler

Garbage Collector and Memory Profiler: MemoryProfiler

This profiler will record:

  1. Heap and non-heap memory usage
  2. Number of GC pauses and GC time

Assuming you use the default prefix of statsd-jvm-profiler, the memory usage metrics will be under statsd-jvm-profiler.heap and statsd-jvm-profiler.nonheap, the GC metrics will be under statsd-jvm-profiler.gc.

Memory and GC metrics are reported once every 10 seconds.

CPU Tracing Profiler: CPUTracingProfiler

This profiler records the time spent in each function across all Threads.

Assuming you use the default prefix of statsd-jvm-profiler, the the CPU time metrics will be under statsd-jvm-profiler.cpu.trace.

The CPU time is sampled every millisecond, but only reported every 10 seconds. The CPU time metrics represent the total time spent in that function.

Profiling a long-running process or a lot of processes simultaneously will produce a lot of data, so be careful with the capacity of your StatsD instance. The packageWhitelist and packageBlacklist arguments can be used to limit the number of functions that are reported. Any function whose stack trace contains a function in one of the whitelisted packages will be included.

The visualization directory contains some utilities for visualizing the output of this profiler.

JVM And System CPU Load Profiler: CPULoadProfiler

This profiler will record the JVM's and the overall system's CPU load, if the JVM is capable of providing this information.

Assuming you use the default prefix of statsd-jvm-profiler, the JVM CPU load metrics will be under statsd-jvm-profiler.cpu.jvm, and the System CPU load wil be under statsd-jvm-profiler.cpu.system.

The reported metrics will be percentages in the range of [0, 100] with 1 decimal precision.

CPU load metrics are sampled and reported once every 10 seconds.

Important notes:

  • This Profiler is not enabled by default. To enable use the argument profilers=CPULoadProfiler
  • This Profiler relies on Sun/Oracle-specific JVM implementations that offer a JMX bean that might not be available in other JVMs. Even if you are using the right JVM, there's no guarantee this JMX bean will remain there in the future.
  • The minimum required JVM version that offers support for this is for Java 7.
  • See com.sun.management.OperatingSystemMXBean for more information.
  • If the JVM doesn't support the required operations, the metrics above won't be reported at all.

Dynamic Loading of Agent

  1. Make sure you have the tools.jar available in your classpath during compilation and runtime. This JAR is usually found in the JAVA_HOME directory under the /lib folder for Oracle Java installations.
  2. Make sure the jvm-profiler JAR is available during runtime.
  3. During your application boostrap process, do the following:
  val jarPath: String = s"$ABSOLUTE_PATH_TO/com.etsy.statsd-jvm-profiler-$VERSION.jar"
  val agentArgs: String = s"server=$SERVER,port=$PORT"
  attachJvmAgent(jarPath, agentArgs)

  def attachJvmAgent(profilerJarPath: String, agentArgs: String): Unit = {
    val nameOfRunningVM: String = java.lang.management.ManagementFactory.getRuntimeMXBean.getName
    val p: Integer = nameOfRunningVM.indexOf('@')
    val pid: String = nameOfRunningVM.substring(0, p)

    try {
      val vm: com.sun.tools.attach.VirtualMachine = com.sun.tools.attach.VirtualMachine.attach(pid)
      vm.loadAgent(profilerJarPath, agentArgs)
      vm.detach()
      LOGGER.info("Dynamically loaded StatsD JVM Profiler Agent...");
    } catch {
      case e: Exception => LOGGER.warn(s"Could not dynamically load StatsD JVM Profiler Agent ($profilerJarPath)", e);
    }
  }

Contributing

Contributions are highly encouraged! Check out the contribution guidlines.

Any ideas you have are welcome, but check out some ideas for contributions.

statsd-jvm-profiler list of languages used
statsd-jvm-profiler latest release notes
2.1.0 Fix Profiler for Java 7

The previous release included an upgrade of the Vertx library used for the embedded HTTP server. The upgraded version required Java 8. The intent was not to drop support for Java 7 so the Vertx upgrade has been reverted.

2.0.0 New JVM and System CPU Load Profiler

Thanks to AlejandroRivera there is a new profiler for measuring overall JVM and system CPU load. It is not enabled by default as it is specific to the Oracle JVM 7+ and may not exist in future versions. See https://github.com/etsy/statsd-jvm-profiler#jvm-and-system-cpu-load-profiler-cpuloadprofiler for details on the new profiler and its use.

1.0.2 Optionally Disable the Embedded HTTP Server

Thanks to AlejandroRivera the embedded HTTP server in the profiler can be disabled by setting the httpServerEnabled=false argument. The profiler is enabled by default.

Other projects in Java