Document new standalone options for PerfTool

[yathamravali]

Issue or pull request number:
eclipse-openj9/openj9#14157
eclipse-openj9/openj9#15823

Overview:
New standalone options helps to enable/disable perftool without worrying about the issue of pre-existing JIT command line options getting clobbered when -Xjit:perfTool is used

Release target:
Eclipse OpenJ9 0.35

Applies to the following JDK versions:
All versions

Applies to the following platforms:
Linux X|P|Z

For new command line options:

• -XX:+PerfTool Enables PerfTool. Functionality is similar to existing option -Xjit:perfTool
• -XX:-PerfTool Disables PerfTool

[Sreekala-Gopakumar]

@yathamravali, @kgibm, @dsouzai - I have noticed that the -Xjit:perfTool option has not been documented in the existing OpenJ9 documents. It is mentioned in the eclipse-openj9/openj9#14157 that this option is something that might be recommended by the service staff/support engineer to the customer, if required. That means the user is not expected to use this option on their own? Is that the reason why it was not documented for the users? If so, then wouldn't I have to skip documenting these new options for the same reason?

If these new options have to be documented, then wouldn't I have to document the -Xjit:perfTool option as well? If yes, then could you please provide some content that I can use for explaining that option. Its use, any default values, range of values or exceptions to be explained? Thanks!

[yathamravali]

@Sreekala-Gopakumar

This is from my understanding:
Even I couldn’t find -Xjit:perfTool documented in command line options. But the usage is explained in this openj9 blog
https://blog.openj9.org/2019/07/18/inspecting-openj9-performance-with-perf-on-linux-jit-compiled-methods/ [ see Investigating with Linux Perf section]

It is mentioned in the eclipse-openj9/openj9#14157 that this option is something that might be recommended by the service staff/support engineer to the customer, if required. That means the user is not expected to use this option on their own?

This is to explain the current behaviour of Xjit options i.e multiple jit options is not recommended and there could be a situation wherein support engineer might recommend a new JIT option without combining with existing option which will override the old Jit options. Don’t think this as the reason for not documenting -Xjit:perfTool option.

-Xjit:perfTool causes the JIT to produce a /tmp/perf-<pid>.map file for JIT compiled code, which the perf report command uses to associate samples to symbols.

By default this option is disabled

Enable PerfTool - -XX:+PerfTool (alias to -Xjit:perfTool)
Disable PerfTool - -XX:-PerfTool

@dsouzai @pshipton - Could you help @Sreekala-Gopakumar on why -Xjit:perfTool is not documented and suggest any further inputs on how to document these new options please?

[doveye]

Just to add to the comments - it looks like -Xjit:perf was added to the IBM SDK for Java 7.1 but wasn't documented. Sometimes options are deliberately not documented because they are supposed to be used only under guidance from support people. We're wondering whether that was the case for this option and whether we do now want to document it.

If -XX:[+|-]PerfTool is preferred because of the problem with overriding of JIT options, maybe we don't want to document -Xjit:perf?

If we do want to document it, we'll need some more info about it (eg the blog post just talks about one use of it on Linux - are there other uses and does it apply on other platforms).

[dsouzai]

I suppose the reason -Xjit:perfTool wasn't documented comes from the default assumption that all JIT options are internal and not supported unless documented. I suppose I don't see any reason why it shouldn't be documented.

-Xjit:perfTool creates a file in /tmp that is used by the Linux system profiler perf to resolve ticks in JIT'd code. It is only active on Linux because it's specific to the perf profiler. The general usage is, if one wishes to profile the JVM using perf on Linux, they should add perfTool to the -Xjit option. After the user stops profiling and terminates the JVM, the file in /tmp is consumed by perf report.

It is worth noting (as described in the blog post linked above) that newer versions of perf come with a JVMTI agent that is used to resolve ticks in JIT'd code. However, for older versions, -Xjit:perfTool is the only means of resolving JIT ticks.

[Sreekala-Gopakumar]

@dsouzai - Is there a difference between -Xjit:perf mentioned by Esther (#983 (comment)) and -Xjit:perfTool?

[dsouzai]

Is there a difference between -Xjit:perf mentioned by Esther (#983 (comment)) and -Xjit:perfTool?

There isn't any -Xjit:perf option, there's only a -Xjit:perfTool option (I verified by double checking in the code base). I think that comment might just be a typo.