opentelemetry-specification icon indicating copy to clipboard operation
opentelemetry-specification copied to clipboard

Metric instrument limit naming

Open jack-berg opened this issue 2 years ago • 1 comments

The metric semantic conventions has the following instrument naming recommendation:

limit - an instrument that measures the constant, known total amount of something should be called entity.limit. For example, system.memory.limit for the total amount of memory on a system.

The java runtime memory semantic conventions has the following instruments:

  • process.runtime.jvm.memory.max
  • process.runtime.jvm.memory.init

The *.max instrument arguably should be renamed to *.limit to align with the naming recommendation. An argument to keep it as is that the idea of max memory is entrenched in java vernacular - renaming it to limit may be surprising.

Separately, instruments that have a max often have something like a minimum value as well. In the case of java memory, its *.init. The naming recommendation of limit doesn't neatly accommodate instruments with a min.

To account for this, we could change the naming recommendation to upper_limit, and include a corresponding lower_limit for symmetry.

jack-berg avatar May 19 '22 19:05 jack-berg

Was thinking more about whether it would be appropriate to change process.runtime.jvm.memory.init to something like process.runtime.jvm.memory.lower_limit. I believe we should not because the init memory isn't actually the lower limit. The init is just the initial amount of memory requested from the system at startup. The JVM can release memory such that the committed memory is lower than the init, as documented here:

The Java virtual machine may release memory to the system and committed could be less than init.

The issue still stands that there will likely be cases where we want to collect the upper and lower limits of something, but in the case of JVM memory, init is a separate concept that doesn't quite fit.

We should rename process.runtime.jvm.memory.max to process.runtime.jvm.memory.limit for consistency until this issue is resolved.

jack-berg avatar May 25 '22 14:05 jack-berg