From df0f54d2acd5b5b6179c35b655bdb511fdfacc38 Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Wed, 20 Nov 2024 11:14:59 +0200 Subject: [PATCH 1/8] add k8s semconv migration non-normative doc Signed-off-by: ChrsMark --- docs/non-normative/k8s-migration.md | 56 +++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 docs/non-normative/k8s-migration.md diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md new file mode 100644 index 0000000000..f0ada4300f --- /dev/null +++ b/docs/non-normative/k8s-migration.md @@ -0,0 +1,56 @@ + + +# K8s semantic conventions stability migration + +Due to the significant number of modifications and the extensive user base +affected by them, existing K8s instrumentations published by +OpenTelemetry are required to implement a migration plan that will assist users in +transitioning to the stable K8s semantic conventions. + +Specifically, when existing K8s instrumentations published by OpenTelemetry are +updated to the stable K8s semantic conventions, they: + +- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in + their existing major version, which accepts: + - `k8s` - emit the stable k8s conventions, and stop emitting + the old k8s conventions that the instrumentation emitted previously. + - `k8s/dup` - emit both the old and the stable k8s conventions, + allowing for a phased rollout of the stable semantic conventions. + - The default behavior (in the absence of one of these values) is to continue + emitting whatever version of the old k8s conventions the + instrumentation was emitting previously. +- Need to maintain (security patching at a minimum) their existing major version + for at least six months after it starts emitting both sets of conventions. +- May drop the environment variable in their next major version and emit only + the stable k8s conventions. + + + +- [Summary of changes](#summary-of-changes) + - [K8s network metrics](#k8s-network-metrics) + + + +## Summary of changes + +This section summarizes the changes made to the K8s semantic conventions +from a range of versions. Each starting version shows all the changes required +to bring the conventions to +[v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/k8s/README.md). + +### K8s network metrics + +The K8s network metrics implemented by the Collector and specifically the +[kubeletstats](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.112.0/receiver/kubeletstatsreceiver/documentation.md) +receiver were introduced as semantic conventions in [v1.TODO](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/k8s/README.md). + +The changes in their attributes are the following: + + +| Old (Collector) ![changed](https://img.shields.io/badge/changed-orange?style=flat) | New | +|------------------------------------------------------------------------------------|---------------------------| +| `interface` | `network.interface.name` | +| `direction` | `network.io.direction` | + From 0f4e20552f3b5d488424f6c5155c5a32d582abaf Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Tue, 26 Nov 2024 12:14:45 +0200 Subject: [PATCH 2/8] Add collector migration guide Signed-off-by: ChrsMark --- docs/non-normative/k8s-migration.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index f0ada4300f..c492fe33c4 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -9,7 +9,7 @@ affected by them, existing K8s instrumentations published by OpenTelemetry are required to implement a migration plan that will assist users in transitioning to the stable K8s semantic conventions. -Specifically, when existing K8s instrumentations published by OpenTelemetry are +When existing K8s instrumentations published by OpenTelemetry are updated to the stable K8s semantic conventions, they: - SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in @@ -26,6 +26,15 @@ updated to the stable K8s semantic conventions, they: - May drop the environment variable in their next major version and emit only the stable k8s conventions. +Specifically for the Opentelemetry Collector: + +The transition will happen through two different feature gates. +One for enabling the new schema, and one for disabling the old schema. Then: + +- On alpha the old schema is enabled, while the new schema is disabled +- On beta/stable the old schema is disabled, while the new is enabled +- It is an error to disable both + - [Summary of changes](#summary-of-changes) @@ -37,14 +46,13 @@ updated to the stable K8s semantic conventions, they: This section summarizes the changes made to the K8s semantic conventions from a range of versions. Each starting version shows all the changes required -to bring the conventions to -[v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/k8s/README.md). +to bring the conventions to stable (TODO: link to specific version once it exists). ### K8s network metrics The K8s network metrics implemented by the Collector and specifically the [kubeletstats](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/v0.112.0/receiver/kubeletstatsreceiver/documentation.md) -receiver were introduced as semantic conventions in [v1.TODO](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/k8s/README.md). +receiver were introduced as semantic conventions in [v1.29.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.29.0/docs/system/k8s-metrics.md). The changes in their attributes are the following: From 7b1289d298a373687a88601b84010f85c83cb48a Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Tue, 26 Nov 2024 12:18:20 +0200 Subject: [PATCH 3/8] add changelog Signed-off-by: ChrsMark --- .chloggen/k8s-migration.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100755 .chloggen/k8s-migration.yaml diff --git a/.chloggen/k8s-migration.yaml b/.chloggen/k8s-migration.yaml new file mode 100755 index 0000000000..f9a4de7bbe --- /dev/null +++ b/.chloggen/k8s-migration.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: k8s + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add migration guide for K8s semantic conventions + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1597] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From 8ca50940fd6203377988cf05a3e78be5ba8df7c0 Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Tue, 26 Nov 2024 16:31:38 +0200 Subject: [PATCH 4/8] add feature gate names Signed-off-by: ChrsMark --- docs/non-normative/k8s-migration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index c492fe33c4..e1baef1690 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -29,7 +29,8 @@ updated to the stable K8s semantic conventions, they: Specifically for the Opentelemetry Collector: The transition will happen through two different feature gates. -One for enabling the new schema, and one for disabling the old schema. Then: +One for enabling the new schema called `semconv.k8s.stable`, +and one for disabling the old schema called `semconv.k8s.legacy`. Then: - On alpha the old schema is enabled, while the new schema is disabled - On beta/stable the old schema is disabled, while the new is enabled From 45073a111035be6958825e37e1e719b76014f463 Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Tue, 26 Nov 2024 17:14:05 +0200 Subject: [PATCH 5/8] add ownership Signed-off-by: ChrsMark --- .github/CODEOWNERS | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 5c2a3334df..edaab04fe1 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -58,8 +58,9 @@ /model/device/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-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/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-migration.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 From 624a9be0bee8cd727c26d80c8ab77ec80b9be3fa Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Wed, 27 Nov 2024 14:23:47 +0200 Subject: [PATCH 6/8] fix feature gate names Signed-off-by: ChrsMark --- docs/non-normative/k8s-migration.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index e1baef1690..fc8c61bf17 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -29,12 +29,15 @@ updated to the stable K8s semantic conventions, they: Specifically for the Opentelemetry Collector: The transition will happen through two different feature gates. -One for enabling the new schema called `semconv.k8s.stable`, -and one for disabling the old schema called `semconv.k8s.legacy`. Then: - -- On alpha the old schema is enabled, while the new schema is disabled -- On beta/stable the old schema is disabled, while the new is enabled -- It is an error to disable both +One for enabling the new schema called `semconv.k8s.enableStable`, +and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then: + +- On alpha the old schema is enabled by default (`semconv.k8s.disableLegacy` defaults to false), + while the new schema is disabled (`semconv.k8s.enableStable` defaults to false). +- On beta/stable the old schema is disabled by default (`semconv.k8s.disableLegacy` defaults to true), + while the new is enabled by default (`semconv.k8s.enableStable` defaults to true). +- It is an error to disable both schemas +- Both schemas can enabled with `--feature-gates=-semconv.disableLegacy,+semconv.k8s.enableStable`. From 2ed8991d5d7d0c702bbbc04d34df6b6f5f575248 Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Mon, 2 Dec 2024 17:19:53 +0200 Subject: [PATCH 7/8] fix typos Signed-off-by: ChrsMark --- docs/non-normative/k8s-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index fc8c61bf17..5b9a64f539 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -33,11 +33,11 @@ One for enabling the new schema called `semconv.k8s.enableStable`, and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then: - On alpha the old schema is enabled by default (`semconv.k8s.disableLegacy` defaults to false), - while the new schema is disabled (`semconv.k8s.enableStable` defaults to false). + while the new schema is disabled by default (`semconv.k8s.enableStable` defaults to false). - On beta/stable the old schema is disabled by default (`semconv.k8s.disableLegacy` defaults to true), while the new is enabled by default (`semconv.k8s.enableStable` defaults to true). - It is an error to disable both schemas -- Both schemas can enabled with `--feature-gates=-semconv.disableLegacy,+semconv.k8s.enableStable`. +- Both schemas can be enabled with `--feature-gates=-semconv.disableLegacy,+semconv.k8s.enableStable`. From 5c1d4612748100ed5e3b08600986940fe766b4d1 Mon Sep 17 00:00:00 2001 From: Christos Markou Date: Mon, 2 Dec 2024 18:54:23 +0200 Subject: [PATCH 8/8] Update docs/non-normative/k8s-migration.md Co-authored-by: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> --- docs/non-normative/k8s-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/non-normative/k8s-migration.md b/docs/non-normative/k8s-migration.md index 5b9a64f539..8a8f305dac 100644 --- a/docs/non-normative/k8s-migration.md +++ b/docs/non-normative/k8s-migration.md @@ -37,7 +37,7 @@ and one for disabling the old schema called `semconv.k8s.disableLegacy`. Then: - On beta/stable the old schema is disabled by default (`semconv.k8s.disableLegacy` defaults to true), while the new is enabled by default (`semconv.k8s.enableStable` defaults to true). - It is an error to disable both schemas -- Both schemas can be enabled with `--feature-gates=-semconv.disableLegacy,+semconv.k8s.enableStable`. +- Both schemas can be enabled with `--feature-gates=-semconv.k8s.disableLegacy,+semconv.k8s.enableStable`.