open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

add k8s.cluster.uid resource attribute semconv (#3267) 

Fixes #3266

## Changes

Kubernetes doesn't have a formal way to identify a cluster, but a
pseudo-id can be derived by taking the `uid` of the `kube-system`
namespace. This PR adds a convention for `k8s.cluster.uid` to be set to
the `kube-system` namespace uid.
This commit is contained in:
Matthew Wear 2023-04-18 14:21:28 -07:00 committed by GitHub
parent bce030702e
commit aa873f0a9b
2 changed files with 53 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
semantic_conventions/resource/k8s.yaml
View File

@ -10,6 +10,35 @@ groups:
brief: >
The name of the cluster.
examples: ['opentelemetry-cluster']
- id: uid
type: string
brief: >
A pseudo-ID for the cluster, set to the UID of the `kube-system`
namespace.
note: |
K8s does not have support for obtaining a cluster ID. If this is ever
added, we will recommend collecting the `k8s.cluster.uid` through the
official APIs. In the meantime, we are able to use the `uid` of the
`kube-system` namespace as a proxy for cluster ID. Read on for the
rationale.
Every object created in a K8s cluster is assigned a distinct UID. The
`kube-system` namespace is used by Kubernetes itself and will exist
for the lifetime of the cluster. Using the `uid` of the `kube-system`
namespace is a reasonable proxy for the K8s ClusterID as it will only
change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are
UUIDs as standardized by
[ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html).
Which states:
> If generated according to one of the mechanisms defined in Rec.
ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be
different from all other UUIDs generated before 3603 A.D., or is
extremely likely to be different (depending on the mechanism chosen).
Therefore, UIDs between clusters should be extremely unlikely to
conflict.
examples: ['218fc5a9-a5f1-4b54-aa05-46717d0ab26d']
- id: k8s.node
prefix: k8s.node

24
specification/resource/semantic_conventions/k8s.md
View File

@ -25,6 +25,30 @@ Kubernetes object, but "name" is usually more user friendly so can be also set.
| Attribute | Type | Description | Examples | Requirement Level |
|---|---|---|---|---|
| `k8s.cluster.name` | string | The name of the cluster. | `opentelemetry-cluster` | Recommended |
| `k8s.cluster.uid` | string | A pseudo-ID for the cluster, set to the UID of the `kube-system` namespace. [1] | `218fc5a9-a5f1-4b54-aa05-46717d0ab26d` | Recommended |
**[1]:** K8s does not have support for obtaining a cluster ID. If this is ever
added, we will recommend collecting the `k8s.cluster.uid` through the
official APIs. In the meantime, we are able to use the `uid` of the
`kube-system` namespace as a proxy for cluster ID. Read on for the
rationale.
Every object created in a K8s cluster is assigned a distinct UID. The
`kube-system` namespace is used by Kubernetes itself and will exist
for the lifetime of the cluster. Using the `uid` of the `kube-system`
namespace is a reasonable proxy for the K8s ClusterID as it will only
change if the cluster is rebuilt. Furthermore, Kubernetes UIDs are
UUIDs as standardized by
[ISO/IEC 9834-8 and ITU-T X.667](https://www.itu.int/ITU-T/studygroups/com17/oid.html).
Which states:
> If generated according to one of the mechanisms defined in Rec.
ITU-T X.667 | ISO/IEC 9834-8, a UUID is either guaranteed to be
different from all other UUIDs generated before 3603 A.D., or is
extremely likely to be different (depending on the mechanism chosen).
Therefore, UIDs between clusters should be extremely unlikely to
conflict.
<!-- endsemconv -->
## Node