Go: Add opt-in CPU metric, and detailed opt-in attributes

[dashpole]

Fixes #3354

Related to open-telemetry/opentelemetry-go-contrib#6321

Also includes a request from golang/go#67120 (comment) for detailed CPU metrics.

Changes

All additions are all opt-in:

• Adds go.cpu.time, which has go.cpu.state and go.cpu.detailed_state.
• Adds go.memory.detailed_type to go.memory.usage.

My goals with this are:

• Provide users with a default set of high-level, stable attributes for CPU and memory metrics.
• Provide advanced users a way to get more detailed attributes for the same metrics that may change with each go version. Don't break usage of the default set of attributes when this is enabled.
• Use the tools provided by the metrics API (opt-in metrics coming soon, opt-in attributes).

The approach i've taken is to use two attributes:

• One default-on attribute: go.cpu.state or go.memory.type, which has a set of stable, well-defined constants that are useful to most users and highly unlikely to change. E.g. "stack" for memory, or "gc" for CPU.
• One opt-in attribute: go.cpu.detailed_state and go.memory.detailed_type, which will provide all of the categories offered by the go runtime for each version: https://pkg.go.dev/runtime/metrics#hdr-Supported_metrics based on a prefix (cpu/classes/* and memory/classes/* respectively).

Enabling the opt-in attribute increases cardinality, since multiple detailed types/states can apply to each of the high-level types/states.

Alternatives Considered

We could instead have separate metrics for detailed and basic attributes. This is more expensive without much benefit.

We could instead change the values reported to the detailed ones based on user configuration. This would break existing usage of the high-level attributes when a user enables the detailed ones.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• Links to the prototypes or existing instrumentations (when adding or changing conventions)
  • open-telemetry/opentelemetry-go-contrib@main...dashpole:opentelemetry-go-contrib:optin_runtime_metrics

Gemini helped me copy descriptions over from the runtime metrics documentation.

@open-telemetry/go-approvers @jmacd

[jmacd]

Thank you @dashpole this looks great.

[joaopgrassi]

One thing that may be confusing with the taken approach is that users may expect that go.memory.detailed_type to be a superset of go.memory.type where in fact it's not. So say the split they metric by the detailed dimension thinking they would also see the "stable" values but they won't.

We could instead change the values reported to the detailed ones based on user configuration. This would break existing usage of the high-level attributes when a user enables the detailed ones.

Did you mean change the values reported on the go.memory.type to include the unstable, detailed ones? I don't really follow how it would break existing usage.

[dashpole]

Did you mean change the values reported on the go.memory.type to include the unstable, detailed ones? I don't really follow how it would break existing usage.

The sum of all attributes must sum to the memory usage of the go process, otherwise it isn't useful. So we can aggregate the detailed, unstable values into higher-leveled ones, but we can't simply omit categories of memory usage without breaking the total. When we aggregate, it would be misleading to re-use the same attribute values to mean different things.

[joaopgrassi]

Looks like the tables need updating, after that we can merge.