Add experimental go runtime metrics semantic conventions

[dashpole]

Fixes #535

Changes

Add experimental runtime metrics based on the proposed set of recommended metrics from the Go team: golang/go#67120

Please direct feedback on the set of metrics on the issue above. If the recommended set is changed, I will update these conventions. Feedback on the OTel representation of those metrics is welcome.

Alternatives considered

Separate metrics for memory usage

Instead of a single go.memory.usage metric, we could have one metric for the total, and other metrics for the stack and released amounts. Separate metrics would potentially be more "future proof", if a new sub-set of memory that overlapped with released or stack memory was ever introduced. I chose the existing design because using labels is easier to visualize, and understand for users.

go.gc.* instead of go.memory.gc.*

This PR uses go.memory.gc.*. Instead, we could use go.gc.*, similar to java's jvm.gc.duration. I went this direction because it is garbage collecting memory, and I felt it was most appropriate to compare the GC target to the go.memory.usage and go.memory.limit metrics.

Different naming for "total" memory metrics

/gc/heap/allocs:bytes and /gc/heap/allocs:objects from the go runtime are both cumulative totals for number and size of allocations made. I've opted to name them go.memory.allocated and go.memory.allocations to be concise, but users may think go.memory.allocated sounds like the same thing as go.memory.usage. Some alternative names I considered:

• go.memory.size_allocated and go.memory.objects_allocated

Note that we cannot use the count or total suffixes per https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#naming-rules-for-counters-and-updowncounters

go.config.gomemlimit instead of go.memory.limit

To be consistent with the other configuration metric, go.config.gogc, we could name the memory limit go.config.gomemlimit. I've opted for the go.memory.limit naming because it aligns with jvm.memory.limit, and because it helps users understand that they should compare memory usage with the limit.

@open-telemetry/go-approvers @felixge @mknyszek

[reyang]

LGTM with some non-blocking clarification questions.

[trask]

Add experimental runtime metrics based on the proposed set of recommended metrics from the Go team: https://docs.google.com/document/d/1NBeEYxld5lA_UUXoFniBO0a6_ryHYgFC0hgUAjpfdDY/edit?resourcekey=0-NBd-0IZAYTtiPej124rR2w&tab=t.0

Can this doc be made publicly accessible?

[felixge]

Thanks for raising this @dashpole . But as mentioned by others, the document you linked hasn't been made public yet. It might also make sense to allow some time for discussing the contents of the document in the Go community. (But since your PR here uses "status: experimental" I guess I don't feel strongly about it)

[dashpole]

Can this doc be made publicly accessible?

I don't believe it can be. Feel free to request access.

[dashpole]

But as mentioned by others, the document you linked hasn't been made public yet. It might also make sense to allow some time for discussing the contents of the document in the Go community. (But since your PR here uses "status: experimental" I guess I don't feel strongly about it)

I'm hoping this will help provide feedback on the proposal. These conventions will be kept experimental until the proposal is finalized.

[mknyszek]

I have posted the proposal on the Go issue tracker; no need to look at the doc anymore. Please comment at golang/go#67120.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: dashpole / name: David Ashpole (3781bae, 998b8ce, 79dad69, 79493af, 16d3a0a, bde0f9b, c527c4b, 66a9965, 9d185f2, 9929f8e, 65fca8d, bf32e4f, a708352, 7ecfa39, eed3414, d1ad50f, 09aeb77, 32e4ebe, c456bb3, 7a4fb6d)

[dashpole]

@reyang anything else needed for this to merge?

[reyang]

@reyang anything else needed for this to merge?

Nope, you're all set 👍