Package com.datadoghq.profiler

Class JavaProfiler

  • public final class JavaProfiler
extends java.lang.Object
    Java API for in-process profiling. Serves as a wrapper around java-profiler native library. This class is a singleton. The first call to getInstance() initiates loading of libjavaProfiler.so.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      void addThread()
      Add the given thread to the set of profiled threads.
      void clearContext()
      Clears context identifier for current thread.
      void dump​(java.nio.file.Path recording)
      Dumps the JFR recording at the provided path
      java.lang.String execute​(java.lang.String command)
      Execute an agent-compatible profiling command - the comma-separated list of arguments described in arguments.cpp
      long getCurrentTicks()
      Get the ticks for the current thread.
      java.util.Map<java.lang.String,​java.lang.Long> getDebugCounters()
      If the profiler is built in debug mode, returns counters recorded during profile execution.
      static JavaProfiler getInstance()
      Get a JavaProfiler instance backed by the bundled native library and using the default temp directory as the scratch where the bundled library will be exploded before linking.
      static JavaProfiler getInstance​(java.lang.String scratchDir)
      Get a JavaProfiler instance backed by the bundled native library and using the given directory as the scratch where the bundled library will be exploded before linking.
      static JavaProfiler getInstance​(java.lang.String libLocation, java.lang.String scratchDir)
      Get a JavaProfiler instance backed by the given native library and using the given directory as the scratch where the bundled library will be exploded before linking.
      long getSamples()
      Get the number of samples collected during the profiling session
      java.lang.String getVersion()
      Get profiler agent version, e.g.
      boolean isThresholdExceeded​(long thresholdMillis, long startTicks, long endTicks)
      Scales the ticks to milliseconds and applies a threshold
      void recordQueueTime​(long startTicks, long endTicks, java.lang.Class<?> task, java.lang.Class<?> scheduler, java.lang.Thread origin)
      Records when queueing ended
      void recordSetting​(java.lang.String name, java.lang.String value)
      Records a datadog.ProfilerSetting event with no unit
      void recordSetting​(java.lang.String name, java.lang.String value, java.lang.String unit)
      Records a datadog.ProfilerSetting event
      boolean recordTraceRoot​(long rootSpanId, java.lang.String endpoint, int sizeLimit)
      Deprecated.
      boolean recordTraceRoot​(long rootSpanId, java.lang.String endpoint, java.lang.String operation, int sizeLimit)
      Records the completion of the trace root
      void removeThread()
      Remove the given thread to the set of profiled threads.
      void setContext​(long spanId, long rootSpanId)
      Passing context identifier to a profiler.
      void setContextByteBuffer​(int tid, int offset, int value)  
      void setContextValue​(int offset, int value)
      Sets a context value
      void stop()
      Stop profiling (without dumping results)

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • getInstance

        public static JavaProfiler getInstance()
                                throws java.io.IOException
        Get a JavaProfiler instance backed by the bundled native library and using the default temp directory as the scratch where the bundled library will be exploded before linking.
        Throws:
        java.io.IOException

      • getInstance

        public static JavaProfiler getInstance​(java.lang.String scratchDir)
                                throws java.io.IOException
        Get a JavaProfiler instance backed by the bundled native library and using the given directory as the scratch where the bundled library will be exploded before linking.
        Parameters:
        scratchDir - directory where the bundled library will be exploded before linking
        Throws:
        java.io.IOException

      • getInstance

        public static JavaProfiler getInstance​(java.lang.String libLocation,
                                       java.lang.String scratchDir)
                                throws java.io.IOException
        Get a JavaProfiler instance backed by the given native library and using the given directory as the scratch where the bundled library will be exploded before linking.
        Parameters:
        libLocation - the path to the native library to be used instead of the bundled one
        scratchDir - directory where the bundled library will be exploded before linking; ignored when 'libLocation' is null
        Throws:
        java.io.IOException

      • stop

        public void stop()
          throws java.lang.IllegalStateException
        Stop profiling (without dumping results)
        Throws:
        java.lang.IllegalStateException - If profiler is not running

      • getSamples

        public long getSamples()
        Get the number of samples collected during the profiling session
        Returns:
        Number of samples

      • getVersion

        public java.lang.String getVersion()
        Get profiler agent version, e.g. "1.0"
        Returns:
        Version string

      • execute

        public java.lang.String execute​(java.lang.String command)
                         throws java.lang.IllegalArgumentException,
                                java.lang.IllegalStateException,
                                java.io.IOException
        Execute an agent-compatible profiling command - the comma-separated list of arguments described in arguments.cpp
        Parameters:
        command - Profiling command
        Returns:
        The command result
        Throws:
        java.lang.IllegalArgumentException - If failed to parse the command
        java.io.IOException - If failed to create output file
        java.lang.IllegalStateException

      • recordTraceRoot

        public boolean recordTraceRoot​(long rootSpanId,
                               java.lang.String endpoint,
                               java.lang.String operation,
                               int sizeLimit)
        Records the completion of the trace root

      • recordTraceRoot

        @Deprecated
public boolean recordTraceRoot​(long rootSpanId,
                               java.lang.String endpoint,
                               int sizeLimit)
        Deprecated.
        Records the completion of the trace root

      • addThread

        public void addThread()
        Add the given thread to the set of profiled threads. 'filter' option must be enabled to use this method.

      • removeThread

        public void removeThread()
        Remove the given thread to the set of profiled threads. 'filter' option must be enabled to use this method.

      • setContext

        public void setContext​(long spanId,
                       long rootSpanId)
        Passing context identifier to a profiler. This ID is thread-local and is dumped in the JFR output only. 0 is a reserved value for "no-context".
        Parameters:
        spanId - Span identifier that should be stored for current thread
        rootSpanId - Root Span identifier that should be stored for current thread

      • clearContext

        public void clearContext()
        Clears context identifier for current thread.

      • setContextValue

        public void setContextValue​(int offset,
                            int value)
        Sets a context value
        Parameters:
        offset - the offset
        value - the encoding of the value. Must have been encoded via @see JavaProfiler#registerConstant

      • setContextByteBuffer

        public void setContextByteBuffer​(int tid,
                                 int offset,
                                 int value)

      • dump

        public void dump​(java.nio.file.Path recording)
        Dumps the JFR recording at the provided path
        Parameters:
        recording - the path to the recording
        Throws:
        java.lang.NullPointerException - if recording is null

      • recordSetting

        public void recordSetting​(java.lang.String name,
                          java.lang.String value)
        Records a datadog.ProfilerSetting event with no unit
        Parameters:
        name - the name
        value - the value

      • recordSetting

        public void recordSetting​(java.lang.String name,
                          java.lang.String value,
                          java.lang.String unit)
        Records a datadog.ProfilerSetting event
        Parameters:
        name - the name
        value - the value
        unit - the unit

      • isThresholdExceeded

        public boolean isThresholdExceeded​(long thresholdMillis,
                                   long startTicks,
                                   long endTicks)
        Scales the ticks to milliseconds and applies a threshold

      • recordQueueTime

        public void recordQueueTime​(long startTicks,
                            long endTicks,
                            java.lang.Class<?> task,
                            java.lang.Class<?> scheduler,
                            java.lang.Thread origin)
        Records when queueing ended
        Parameters:
        task - the name of the enqueue task
        scheduler - the name of the thread-pool or executor scheduling the task
        origin - the thread the task was submitted on

      • getCurrentTicks

        public long getCurrentTicks()
        Get the ticks for the current thread.
        Returns:
        ticks

      • getDebugCounters

        public java.util.Map<java.lang.String,​java.lang.Long> getDebugCounters()
        If the profiler is built in debug mode, returns counters recorded during profile execution. These are for whitebox testing and not intended for production use.
        Returns:
        a map of counters