diff --git a/.chloggen/k8s-naming.yaml b/.chloggen/k8s-naming.yaml new file mode 100644 index 000000000..e16f709b5 --- /dev/null +++ b/.chloggen/k8s-naming.yaml @@ -0,0 +1,7 @@ +change_type: enhancement + +component: k8s + +note: Explains the rationale behind the Kubernetes resource naming convention. + +issues: [2245] diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e09b1db5e..83b70cab0 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -77,10 +77,11 @@ /model/mobile/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-client-approvers # K8s semantic conventions -/docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers -/model/k8s/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers -/docs/non-normative/k8s-attributes.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers -/docs/non-normative/k8s-migration.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/model/k8s/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/docs/non-normative/k8s-attributes.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/docs/non-normative/k8s-migration.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers +/docs/non-normative/naming-known-exceptions.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers # Container semantic conventions /docs/resource/container.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-container-approvers diff --git a/docs/general/naming.md b/docs/general/naming.md index 120ff55f6..ee57d76b2 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -75,6 +75,8 @@ Names SHOULD follow these rules: words by underscores (i.e. use snake_case). For example `http.response.status_code` denotes the status code in the http namespace. + Known exceptions include [K8s API names](../non-normative/naming-known-exceptions.md#kubernetes-naming-exceptions) where a single word is used for consistency with the instrumented API. + Use underscore only when using dot (namespacing) does not make sense or changes the semantic meaning of the name. For example, use `rate_limiting` instead of `rate.limiting`. diff --git a/docs/non-normative/naming-known-exceptions.md b/docs/non-normative/naming-known-exceptions.md new file mode 100644 index 000000000..7936b2e74 --- /dev/null +++ b/docs/non-normative/naming-known-exceptions.md @@ -0,0 +1,20 @@ + + +# Kubernetes naming exceptions + +Kubernetes users are accustomed to the single-word resource names used in the Kubernetes API (e.g., `replicaset`, `statefulset`, `daemonset`, `replicationcontroller`, `resourcequota`). Using these same names in telemetry data makes it easier for users to map the data to familiar Kubernetes concepts and commands (e.g., `kubectl get replicaset`). + +When naming entities, attributes, or metrics related to Kubernetes objects, prioritize using the exact single-word form from the official Kubernetes API object names (i.e., borrow the existing single-word term from the API when there is a 1:1 mapping). The official list of API object names can be found in the [Kubernetes API reference documentation](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.33/). For new terms or fields, follow the [general naming considerations](../general/naming.md). + +## Naming Recommendations + +- For resources that map 1:1 to Kubernetes API object names, use the exact single-word form from the Kubernetes API (no underscores, words concatenated as in the API). + +### Examples + +```text +Use: k8s.replicaset.uid (not k8s.replica_set.uid) +Use: k8s.resourcequota.uid (not k8s.resource_quota.uid) +``` diff --git a/docs/resource/k8s.md b/docs/resource/k8s.md index babd665b7..78d10c968 100644 --- a/docs/resource/k8s.md +++ b/docs/resource/k8s.md @@ -531,3 +531,4 @@ A ResourceQuota provides constraints that limit aggregate resource consumption p The following guidelines are specific to Kubernetes: - [Service in Kubernetes](../non-normative/k8s-attributes.md#service-attributes) +- [Additional naming guidance for Kubernetes](../non-normative/naming-known-exceptions.md#kubernetes-naming-exceptions)