Use consistent suffix for JVM Metrics

[lenin-jaganathan]

While going through

semantic-conventions/docs/jvm/jvm-metrics.md

Lines 15 to 38 in 4bbb8c9

	- [JVM Memory](#jvm-memory)
	* [Metric: `jvm.memory.usage`](#metric-jvmmemoryusage)
	* [Metric: `jvm.memory.committed`](#metric-jvmmemorycommitted)
	* [Metric: `jvm.memory.limit`](#metric-jvmmemorylimit)
	* [Metric: `jvm.memory.usage_after_last_gc`](#metric-jvmmemoryusage_after_last_gc)
	- [JVM Garbage Collection](#jvm-garbage-collection)
	* [Metric: `jvm.gc.duration`](#metric-jvmgcduration)
	- [JVM Threads](#jvm-threads)
	* [Metric: `jvm.thread.count`](#metric-jvmthreadcount)
	- [JVM Classes](#jvm-classes)
	* [Metric: `jvm.class.loaded`](#metric-jvmclassloaded)
	* [Metric: `jvm.class.unloaded`](#metric-jvmclassunloaded)
	* [Metric: `jvm.class.count`](#metric-jvmclasscount)
	- [JVM CPU](#jvm-cpu)
	* [Metric: `jvm.cpu.time`](#metric-jvmcputime)
	* [Metric: `jvm.cpu.count`](#metric-jvmcpucount)
	* [Metric: `jvm.cpu.recent_utilization`](#metric-jvmcpurecent_utilization)
	- [Very experimental](#very-experimental)
	* [Metric: `jvm.memory.init`](#metric-jvmmemoryinit)
	* [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization)
	* [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m)
	* [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage)
	* [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit)
	* [Metric: `jvm.buffer.count`](#metric-jvmbuffercount)

, it seems like the suffices for some of the metrics seem to be inconsistent with one another and are also not so straight forward.

I propose replacing the suffix "usage" (noun) in the following metrics with "used" (verb),

• jvm.memory.usage
• jvm.memory.usage_after_last_gc
• jvm.buffer.memory.usage

All these represent the amount being used. In addition, the description already uses the word "used" to describe these metrics and the JMX methods also use the word "used". Also, the sibling metrics use the verb form. E.g: "jvm.memory.committed"

[trask]

hi @lenin-jaganathan!

.usage is a common suffix used in otel semconv, check out

• https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#instrument-naming
• Document common metric names and when they should be used #211 (comment)

so we would probably need to have that discussion (usage -> used) more broadly than only JVM metrics

I personally think either nouns or adjectives (when it describes the namespace which is a noun) seem like good metric names, e.g.

• jvm.memory.committed - measure "committed memory"
• jvm.class.loaded - measures "loaded classes"

[trask]

I realized, I don't think we would want to rename usage -> used generally, e.g. system.memory.usage has dimensions:

• total
• used <--
• free
• shared
• buffers
• cached

@lenin-jaganathan wdyt? do you want to keep this issue open? thx

[lenin-jaganathan]

I would still like this to be addressed. There is a subtle difference between system.memory.usage and jvm.memory.usage.

As you mentioned, the first metric has multiple states - used, free, cached, etc. But the JVM metric is all about using part of it and we have separate metrics for committed, limit, etc. But even in the system metrics use-case, total as a dimension is always a questionable choice since we would expect adding up all the dimensions should be total.

[trask]

But even in the system metrics use-case, total as a dimension is always a questionable choice since we would expect adding up all the dimensions should be total.

ya, this is being addressed in #409:

Removes total from list of well-known values for system.memory.state

can you re-summarize your reasoning for renaming jvm.memory.usage to jvm.memory.used? I think that will help focus this issue, since we've discussed a few different things above, thx

[trask]

ah, I think I understand now

jvm.memory.usage isn't really a parallel to system.memory.usage, since jvm.memory.usage is only one dimension of "usage", namely the used dimension

[trask]

same would apply to

• jvm.memory.usage_after_last_gc
• jvm.buffer.memory.usage

[trask]

looking at other *.usage metrics

• db.client.connections.usage / db.client.connections.limit
  • has state dimension (used / idle)
• hw.gpu.memory.usage / hw.gpu.memory.limit
  • no state dimension <---
• hw.logical_disk.usage / hw.logical_disk.utilization / hw.logical_disk.limit
  • has state dimension (used / free)
• process.memory.usage
  • no state dimension <---
• system.memory.usage / system.memory.utilization
  • has state dimension (used / free / shared / buffers / cached)
• system.paging.usage / system.paging.utilization
  • has state dimension (used / free)
• system.filesystem.usage / system.filesystem.utilization
  • has state dimension (used / free / reserved)

[trask]

There seem to be two options for jvm.memory.usage:

Option 1

Rename jvm.memory.usage to jvm.memory.used

Option 2

Keep the name, but add jvm.memory.state dimension:

• used
• free (which would be committed limit minus used)

and remove the jvm.memory.committed metric

[trask]

I don't think I got Option 2 right above.

I think free should be jvm.memory.limit minus used, see https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#instrument-naming:

usage - an instrument that measures an amount used out of a known total (limit) amount should be called entity.usage. For example, system.memory.usage with attribute state = used | cached | free | ... for the amount of memory in a each state. Where appropriate, the sum of usage over all attribute values SHOULD be equal to the limit.

In which case we'd probably leave jvm.memory.committed metric as-is.

[trask]

Discussed in Java SIG meeting today:

• Not all memory pools have a limit, and so jvm.memory.usage doesn't follow the conventions for .usage (https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#instrument-naming):

  an instrument that measures an amount used out of a known total (limit) amount

• We could still introduce free dimension for pools which have a limit, but we think free will be confusing if we define it as limit - used since there is some precedence in the Java that free = committed - used (https://docs.oracle.com/javase/8/docs/api/java/lang/Runtime.html#freeMemory--)

• jvm.memory.used has the added benefit of matching the underlying Java method https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryUsage.html#getUsed--, similar to how jvm.memory.committed matches https://docs.oracle.com/javase/8/docs/api/java/lang/management/MemoryUsage.html#getCommitted--