Documentation for YJIT.runtime_stats output?

[dogweather]

Are the meanings of the values and their units documented anywhere? Maybe in a source code file? I haven't been able to find it.

My use case: I want to figure out how much memory to set via --yjit-exec-mem-size. To do that, I need to know the meaning of the runtime_stats output entries such as inline_code_size and outlined_code size. I.e., are those relevant to my particular use case? Do the integer numbers represent bytes, blocks of memory, KB, or something else?

Where would I find the answers to those questions?

[noahgibbs]

Hi! Short version: not really. For your specific question, the answer is basically that inline_codesize and outlined_code_size are in bytes, so you'll need to divide by (1024 * 1024) to compare them to the MiB that you give to --yjit-exec-mem-size.

[noahgibbs]

My understanding is that at this point YJIT no longer crashes when it hits the exec-mem-size ceiling, it just stops generating new code. So it's a speed penalty instead of a crash. @XrXr - am I right about that?

With that said, it's nice not to stop JITting early. So it's still good to provide an appropriate value for exec-mem-size.

[noahgibbs]

We should probably document that kind of thing in doc/yjit somewhere, come to think of it. So we do have a place for that. I'll self-assign this and write some docs. We won't be doing full documentation on the stats array for all cases. But the ones that are available even without a compile-time constant should definitely get at least basic documentation.

[dogweather]

Thanks for the info!

[XrXr]

it just stops generating new code. So it's a speed penalty instead of a crash.

That's right. Work is underway so YJIT will consume much less memory by default, hopefully removing the need for tuning --yjit-exec-mem-size in typical usages. With that in mind, I don't feel that we want to commit to supporting the output of the stats hash. Like the module level docs says, there is no API stability guarantee for anything in the module.

More docs can be helpful for sure, but keep in mind that we'll need to update them when the status quo changes.

[maximecb]

I'm in agreement with @XrXr that this is subject to change and we don't necessarily want people to rely on it. I'm not opposed to specifically documenting what inline code size and outlined code size means, but it's probably not worth it documenting the entire output of stats in details. Will close this issue for now.

[dogweather]

How about the current output, inline_code_size and outlined_code? Are those useful to an app developer or deploy engineer?

[maximecb]

Can be useful to know how much code is being generated and how much of the executable memory space is being used with the current system.

[dogweather]

How do those two variables differ?

[dogweather]

I'm trying to find out what info they report. If there's a doc somewhere, I'm happy to read it.

inline_code_size is bytes used? (Just guessing)

outlined_code is ... ?

[noahgibbs]

For your immediate use, the answer is "just add the two together" -- both are generated code size and count against your total.

If you're curious why there are two kinds of code, the YJIT hacking guide in the CRuby source code is your first stop: https://github.com/ruby/ruby/blob/master/doc/yjit/yjit_hacking.md