Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Add documentation for tr.jit options #70

Closed

Conversation

gireeshpunathil
Copy link
Contributor

The goal is to provide as much documentation around

  • Optimizations
  • Control knobs
  • debug options
  • environment variable

Possibly with the help of a sample code, input and output.
Build incrementally, if possible by wider set of contributors.

Fixes: #33

Signed-off-by: Gireesh Punathil [email protected]

@andrewcraik
Copy link
Contributor

andrewcraik commented Sep 19, 2017

Information on the fine grain debug and control knobs needs to live in the code near the knobs otherwise it will get very stale very fast. High-level overviews like how to log, how to control compilation etc are good to document in this kind of how-to, but low-level details need to live in the code near their use in my opinion.

@gireeshpunathil
Copy link
Contributor Author

While it is a WIP, I request an early review on the content, structure, level of detail and format so that the rest of the effort can be aligned for better consumption. thanks!

Copy link
Contributor

@mgaudet mgaudet left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • doc/compiler/ exists for documenting things about the compiler in OpenJ9, though, it could make sense to retitle to JIT (though, with AOTs involvement, ¯\_(ツ)_/¯)
  • It's comparatively rare for people to refer to this as tr.jit; the OpenJ9 JIT, Testarossa are both names that seem to be in more common use.

doc/jit.md Outdated
@@ -0,0 +1,44 @@
# Testarossa JIT (tr.jit) compiler

Testarossa JIT compiler is a high performant dynamic compiler that powers openj9 - an enterprise-grade Java Virtual Machine (JVM). It's characteristic features are to compress the application code for improved runtime performance by exploiting the exact host CPU model and apply profiling on the runtime behavior of the generated code, feed it back to the optimizer to further refine it. The component provides a wide range of command line options to (i) trace the actions of the compilation and the compiled code, and (ii) control the compiler behavior.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • 'high performance', or 'highly performant'
  • 'OpenJ9', not 'openj9'
  • Talking in the abstract about the component is odd -- I'd instead simply talk about the 'compiler'

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks @mgaudet - made those changes.

While care is taken at the design itself to derive optimal performance under default configurations for the most common workloads, these command line options help to derive insight into the efficiency of the compiler for a given workload, and fine tune the compilation behavior for maximizing the runtime performance / throughput.


This page contains the full list of compiler options that are classified into: (i) optimization control knob options (which generally takes the form of enable | disable syntax), (ii) trace options (which generally take the form of traceXXX syntax), and (iii) debug options (which generally helps to manually control the execution on a specific compilation / compiled code event) and (iv) Environment variables that influences the behavior of JVMs that are spawned within that environment.
Copy link
Contributor

@mgaudet mgaudet Sep 19, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tend to agree with Andrew, that detail should probably not live in this document; doubly so since a good chunk of this would end up reproducing the Testarossa Problem Determination Guide from OMR

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 to creating a problem determination guide or linking to the IBM J9 documentation given that there's existing documentation for many of the components there.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify, the PD is not the main intent of this document. Excerpt from #33:

  • Users to gain insight into the (so far) under-documented tr jit features, take advantage of it by applying fine grained compiler customizations based on the specific environment and workload.
  • Community members to better acquiant with the optimizations, hack around with the code with ease, get upto speed for large scale collaboration.

However, I have now linked the section with the PD guide from Eclipse OMR page.


## Control options

### Disable JIT
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I almost think it would be best to document -Xtrace first :)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

thanks - sure, I will try to place a one liner for Xtrace. I will keep it minimal as:

  • -Xtrace usage in this document will be limited,
  • the limited usage of it here will be mostly intuitive to the readers.

@andrewcraik
Copy link
Contributor

Disabling the JIT is a very coarse tool - initial docs would be on logging a method, gathering vlogs etc which are things we have already discussed in some items here on the project.

…ch as

possible with the help of a sample code. Build incrementally,
if possible by wider set of contributors, through squash and merge.

Fixes: eclipse-openj9#33

Signed-off-by: Gireesh Punathil <[email protected]>
@gireeshpunathil
Copy link
Contributor Author

Have left some comments above. In general, please consider this doc with the view of:

  • Ease of consumption and adoption
  • Developer acquaintance
  • Entry point to the source (which is otherwise difficult to reach directly)

@gireeshpunathil
Copy link
Contributor Author

Thanks @andrewcraik - agree that tracing should come first before controlling. I will reverse the order of sections: (i) Know the compiler behavior (ii) Modify the compiler behavior

@DanHeidinga
Copy link
Member

Please add [ci-skip] to the commit message so this commit won't trigger travis.ci builds as this is a docs only change.

@gireeshpunathil
Copy link
Contributor Author

@DanHeidinga - sure, will follow that next time.

@DanHeidinga
Copy link
Member

@gireeshpunathil your enthusiasm and interest in OpenJ9 is very appreciated!

The direction we should be taking for the initial set of documentation for the JIT (and frankly, all components) is to guide users and developers to:

  • understand what the JIT is doing,
  • trace what is getting compiled, determine if any compilations are failing, and why they're failing,
  • work around any bugs they may experience.

These topics are covered in the OMR problem determination (PD) guide. OpenJ9 should provide link to that document and enhance it for Java-specific JIT PD.

fine tune the compilation behavior for maximizing the runtime performance / throughput.

End users should never have to fine tune the JIT to get maximum performance. When a user has to resort to esoteric options to control compilation, we as JVM developers have missed the boat.

If the first google result is a page of JIT compilation options, the project is setting the wrong expectation for users.

I'll repeat @andrewcraik's comment from above:

Information on the fine grain debug and control knobs needs to live in the code near the knobs otherwise it will get very stale very fast.

If you're interested in documenting those options, great! Please do so as comments directly in the code base where developers who may be working with them will see them, not as end user documentation.

Thanks for interest and work on OpenJ9.

@samkamer
Copy link

samkamer commented Sep 29, 2017

If it is an external optimization option, that can be set from the command line or through system properties, how can it be documented only in the code ?

We have three different personas that are the consumers of the OpenJ9 project - 1. a Virtual Machine developer or enthusiast who knows or wants to know the VM internals and wants to contribute to the OpenJ9, 2. a Cloud service administrator / Cloud dev-ops engineer / Cloud / SaaS support engineer who needs to deploy J9 based Runtime and 3. a Java Cloud application developer who wants to get the optimal performance from their Java application.

What @DanHeidinga said above

understand what the JIT is doing,
trace what is getting compiled, determine if any compilations are failing, and why they're failing,
work around any bugs they may experience.

makes perfect sense for persona 1.
But for persona 2 and persona 3 personas above, we should have an out of the code, external documentation of the options and their control knobs, excluding the experimental ones.

As a car driver (3), I do not want to look at the engine under the hood or even inside the wheel to know the optimal air pressure to have in my tires.
As an open standard car driver who is DIY enthusiast (2 and 3), I love the OBD II (On-Board Diagnostics, version II) scan tool, that allows me to figure out the 'Check Engine Light' codes by myself, without having to pop to hood.

@andrewcraik
Copy link
Contributor

@samkamer I still respectfully disagree. Experimental options added by developers for debugging and testing are not something personas 2 and 3 should care about or look at - they are not necessarily stable and should not be used in production settings. In general, failure of the JIT to perform under default settings is a bug - the JIT control logic is not working right or there is an optimization bug. I would rather have those issues brought to the community for them to be analyzed, explored and understood. We can then make improvements that benefit everyone and make things work even better out-of-the-box. If options proliferate in everyday usage and, as a community, we encourage that then changes in options etc will break people and worse, general performance improvements may not be seen.

Documentation on how to log a failure and basic diagnostic options is a good idea since those are what people need to do to bring an issue to the community for discussion. Once you move beyond the diagnostic gathering you are going to be look at the code and so in code documentation should be fine and will remain more current.

@samkamer
Copy link

samkamer commented Oct 2, 2017

Experimental options added by developers for debugging and testing are not something personas 2 and 3 should care about or look at - they are not necessarily stable and should not be used in production settings.

No disagreement there about experimental options.
Unless we are saying that all JIT optimization options are experimental by nature OR the defaults set are optimal for all workloads and scenarios; the tried and tested optimization options need to be documented outside the code. For some of those documented we can even recommend Not to Use in production. They will still be helpful for persona 2 and 3 to understand and optimize the behavior of their cloud runtime and/or applications.
The external documentation will also be helpful for personas 2 and 3 to 1. bring the right data to the community with their issue, saving at least one round trip and 2. learn the usage and analysis, so that next time around participate in the analysis that happens in the community.

@andrewcraik
Copy link
Contributor

The tried and tested optimization options generally not -Xjit options - things like -Xquickstart, -Xshareclassess etc. Pretty much all of the options under -Xjit are for debug and experimentation. They are not generally used in production since the combination of more official -X options combined with the JIT logic should be enough. We may wish to document a few debugging strategies, but with only a very limited set of options.

Documentation around perf analysis and how to bring the right data is certainly a good idea. Making sure everyone can bring perf issues to the table for discussion is very important in us having a great community and a good user run experience so I am very supportive of this aspect of the effort.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants