Add system-specific naming guidance

[lmolkova]

This is blocked on #1734 which implements this guidance for databases.

Fixes #1494, #608

Related:

• Change azure_ and az. to azure. across all conventions #1698
• Demo - remove root namespace from system-specific attributes and metrics #1711

Documents:

• Systems-specific attribute names follow {system_name}.{thing}.{property} pattern
• Systems-specific metric names follow {system_name}.client|server.{metric_name}
• Metrics for remote call operations should include some indication if they are client or server
• System names should not be ambiguous and match the project name or, in most cases, are prefixed with company/org name

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]
• schema-next.yaml updated with changes to existing conventions.

[lmolkova]

the difference with signalr.server.connection.duration below makes me think if we should simplify it and do cosmosdb.client.operation.request_charge. What's the benefit of having db in front of it?

[lmolkova]

summoning @open-telemetry/semconv-system-approvers

It's the same question as for system.linux vs linux metrics in #1403 or #1618

[ChrsMark]

The difference with process.linux.cgroup is that the name describes effectively a cgroup that belongs to a linux process. While cosmosdb.client.operation.request_charge can stand on its own without the need of db in front.

Maybe we can try and standardize this difference as part of this doc?

Note: if we had linux.cgroup it won't be clear if we refer to a linux system/host or a linux process

[trask]

what about linux.process.cgroup?

[lmolkova]

Examples:

• [Imaginary] linux.distro.name (linux.distro.version, linux.kernel.version) instead of os.linux.distro.name or system.linux.distro.name
• [Real] jvm.system.cpu.load_1m instead of system.jvm.cpu.load_1m
• [Real] dotnet.process.cpu.count instead of process.dotnet.cpu.count
• [Real, but different pattern] linux.memory.slab.usage (or linux.system.memory.slab.usage) instead of system.linux.memory.slab.usage

Justification for linux.process.cgroup - cgroup is a property of a process, not linux. E.g. we have process.pid. What if there was a linux-specific process id, would we do linux.process.pid or process.linux.pid ? I think former is more friendly.

And since linux-specific metrics fall into 'specialist case' bucket, they don't necessarily need to be discoverable when you type process and let autocomplete guide you

[trask]

really appreciate all of the guidance documentation!