gProfiler Configuration Options

Perf-less Mode

It is possible to run gProfiler without using perf. Running gProfiler without perf is useful if perf can't be used, for example when the user doesn’t have the correct permissions on the machine or cluster. To enable this mode, use --perf-mode disabled and proceed as normal.

In perf-less mode, gProfiler uses runtime-specific profilers only, and their results are concatenated rather than merged into the results collected by perf. Accordingly, although the results from different profilers are viewed on the same graph, they are not necessarily on the same scale. Users should therefore compare on the same runtime, for example the sample count of Java to Java, rather than the sample count of Java to Python.

Runtime Configurations

• Java Options

  • --no-java or --java-mode disabled: Disable profilers for Java.

  • --no-java-async-profiler-buildids: Disable embedding of buildid+offset in async-profiler native frames (used when debug symbols are unavailable).

• Python Options

  • --no-python: Alias of --python-mode disabled.

  • --python-mode: Controls which profiler is used for Python.

    • auto: (default) try with PyPerf (eBPF), fall back to py-spy.

    • Pyperf: Use PyPerf with no py-spy fallback.

    • pyspy/py-spy: Use py-spy.

    • disabled: Disable profilers for Python.

Profiling using eBPF incurs lower overhead & provides kernel stacks. This (currently) requires kernel headers to be installed.

• PHP Options

  • --php-mode phpspy: Enable PHP profiling with phpspy.

  • --no-php or --php-mode disabled: Disable profilers for PHP.

  • --php-proc-filter: Process filter (pgrep) to select PHP processes for profiling (this is phpspy's -P option)

• Ruby Options

  • --no-ruby or --ruby-mode disabled: Disable profilers for Ruby.

• NodeJS Options

  • --nodejs-mode: Controls which profiler is used for NodeJS.

    • None: (default) no profiler is used.

    • Perf: augment the system profiler (perf) results with jitdump files generated by NodeJS. This requires running your node processes with --perf-prof (and for Node >= 10, with --interpreted-frames-native-stack). See this NodeJS page for more information.

• System Options

  • --perf-mode: Controls the global perf strategy. Must be one of the following options:

    • fp: Use Frame Pointers for the call graph

    • dwarf: Use DWARF for the call graph (adds the --call-graph dwarf argument to the perf command)

    • smart: Run both fp and dwarf, then choose the result with the highest average of stack frames count, per process.

    • disabled: Avoids running perf at all. See perf-less mode.

Other Configurations

• Metrics and Metadata Collection

  • Use --disable-metrics-collection to disable metrics collection

  • Use --disable-metadata-collection to disable metadata collection

By default, gProfiler agent sends system metrics (CPU and RAM usage) and metadata. The metadata includes system metadata like the kernel version and CPU count, and cloud metadata like the type of the instance you are running on. The metrics collection will not be enabled if the --upload-results/-u flag is not set. Otherwise, you can disable metrics and metadata by using the above parameters.

• Profiling Frequency

  • --profiling-frequency: The sampling frequency of the profiling, in hertz.

The default profiling frequency is 11 hertz. Using higher frequency will lead to more accurate results, but will create greater overhead on the profiled system & programs.

• Profiling Duration

  • --profiling-duration: The duration of each profiling session, in seconds.

• Continuous Mode

  • gProfiler can be run in a continuous mode, profiling periodically, using the --continuous/-c flag. Note that when using --continuous with --output-dir, a new file will be created during each sampling interval. Aggregations are only available when uploading to the Granulate Performance Studio.