Document common metric names and when they should be used

[trask]

E.g.

• .count
• .total
• .duration
• .time
• .usage
• .size
• .utilization
• .limit
• .io

[trask]

.duration vs .time

looking at current usage:

.time:

• system.cpu.time
• process.cpu.time
• jvm.cpu.time

.duration:

• http.server.duration
• http.client.duration
• rpc.server.duration
• rpc.client.duration
• jvm.gc.duration

it's not clear to me that having both .time and .duration is justified, as I think using .time for them all is equally good:

• http.server.request.time
• http.client.request.time
• rpc.server.request.time
• rpc.client.request.time
• jvm.gc.time

EDIT: a couple possible pros about keeping .duration

• the .duration name matches the span attribute duration, and in the http/rpc cases these metrics match the corresponding span duration
• .duration could be reserved for histograms, which capture individual durations instead of total time
• .duration is measuring discrete events

[trask]

.count vs .usage vs .size

looking at current usage:

.count

• system.processes.count
• jvm.threads.count
• jvm.buffer.count
• jvm.classes.count (Rename jvm.classes.current_loaded to jvm.classes.count #60)

.usage

• db.client.connections.usage / db.client.connections.max
• hw.gpu.memory.usage / hw.gpu.memory.utilization / hw.gpu.memory.usage
• hw.logical_disk.usage / hw.logical_disk.utilization / hw.logical_disk.limit
• process.memory.usage
• jvm.memory.usage / jvm.memory.limit
• jvm.buffer.usage / jvm.buffer.limit
• system.memory.usage / system.memory.utilization
• system.paging.usage / system.paging.utilization
• system.filesystem.usage / system.filesystem.utilization

.usage appears to be primarily used for metrics with unit Byte

interestingly, jvm.buffers.* has both .count (number of buffers) and .usage (bytes used by those buffers), which makes it confusing which one jvm.buffers.limit applies to (at least without looking at the unit for jvm.buffers.limit)

.size

• http.server.request.size
• http.server.response.size
• http.client.request.size
• http.client.response.size
• rpc.server.request.size
• rpc.server.response.size
• rpc.client.request.size
• rpc.client.response.size
• hw.physical_disk.size

[trask]

Some notes on usage vs limit vs utilization:

• prior discussion Add process.cpu.count metric opentelemetry-specification#2392 (comment)
• usage and limit are the underlying data
• utilization is what people often want, but can be derived
• require all 3 metrics?
• have 1 or 2 of them be opt-in?

.count vs .usage

• usage has a real unit (Bytes)
• count is for unitless, i.e. {request}, {connection}

nice to always use .usage whenever there's a .limit

db.client.connections.usage / db.client.connections.max

• option a: db.client.connections.count / db.client.connections.limit
• option b: db.client.connections.usage / db.client.connections.limit

connections don't necessarily have to use connection pool, in which case you could still report db.client.connections.usage and just not report a limit

[mateuszrzeszutek]

it's not clear to me that having both .time and .duration is justified, as I think using .time for them all is equally good:

Not sure if it matters that much, but all of your .time examples are counters, and all .durations are histograms.

[trask]

notes from semconv meeting:

db.client.connections.usage isn't "current number of active connections", it has dimensions "active"/"idle", so .limit is sum of .usage

[joaopgrassi]

This was closed by mistake by the stale bot. Re-opening