diff --git a/CHANGELOG.md b/CHANGELOG.md index 52188613a7c..f0765df35b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -101,6 +101,8 @@ release. ### Semantic Conventions +- Add k8s.cluster.uid semantic convention + ([#3267](https://github.com/open-telemetry/opentelemetry-specification/pull/3267)) - Clarify that attribute requirement levels apply to the instrumentation library ([#3289](https://github.com/open-telemetry/opentelemetry-specification/pull/3289)) - Fix grammatical number of metric units. diff --git a/semantic_conventions/resource/k8s.yaml b/semantic_conventions/resource/k8s.yaml index 1513f201663..32a9716dbe6 100644 --- a/semantic_conventions/resource/k8s.yaml +++ b/semantic_conventions/resource/k8s.yaml @@ -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 diff --git a/specification/resource/semantic_conventions/k8s.md b/specification/resource/semantic_conventions/k8s.md index 2b2387c54c6..25dfe2e3781 100644 --- a/specification/resource/semantic_conventions/k8s.md +++ b/specification/resource/semantic_conventions/k8s.md @@ -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. ## Node