Clarify how to report the total amount of memory

[mx-psi]

Updates open-telemetry/build-tools#127

Changes

• Removes total from list of well-known values for system.memory.state
• Adds note to system.memory.usage clarifying that adding over system.memory.state SHOULD equal the total amount of memory available in the system.
• Adds opt-in system.memory.limit metric that reports the total amount of memory available in the system.

This tries to follow the guidance on https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#instrument-naming:

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.

and

Where appropriate, the sum of usage over all attribute values SHOULD be equal to the limit.

The total value was added on open-telemetry/build-tools#89 but was not listed before the refactoring. This rewording avoids an inconsistency with the general guidelines and adds a metric that may be useful in some implementations given that total is reported separately by certain OSs (e.g. Linux).

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• CHANGELOG.md updated for non-trivial changes.
• schema-next.yaml updated with changes to existing conventions.

[jsuereth]

Can you open a bug to provide a mechanism in Schema-Files to denote an attribute being dropped?

Yes, it's a breaking change, we're actually going to try to encode breaking changes in SCHEMA over time.

[mx-psi]

Can you open a bug to provide a mechanism in Schema-Files to denote an attribute being dropped?

#1054 is related (although it refers to a different instance where the values were renamed, not dropped). Does that work? Or should we file a new one?

[tigrannajaryan]

I think this can be a non-breaking change:

• system.memory.usage{system.memory.state=used|free|shared|buffers|cached} -> system.memory.usage{system.memory.state=used|free|shared|buffers|cached} // i.e. remain as is
• system.memory.usage{system.memory.state=total} -> system.memory.limit

We can define a rewite transform which will be a more generalized version of the existing split transform.