From 30b2a6ba23bdaa5cb8786d6669ebff6b9f07004c Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Wed, 20 Sep 2023 15:32:33 +0200 Subject: [PATCH 01/10] [CONTRIBUTING.md] Add section about merging ECS conventions --- CONTRIBUTING.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5721670ffa..7940b68f74 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,4 +180,21 @@ make misspell-correction - Send staging tag as PR for review. - Create a tag `v{version}` on the merged PR and push remote. +## Merging existing ECS conventions + +The Elastic Common Schema (ECS) is being merged into OpenTelemetry Semantic +Conventions per [OTEP 222][otep222]. When adding a semantic convention that +exists in some form in ECS, consider the following guidelines: + +- Prefer using the existing ECS name when possible. In particular: + - Do not amend ECS names to follow plural guidelines or other syntactical + attribute naming rules. + - If proposing a name that differs from the ECS convention, provide usage + data, user issue reports or feature requests or comparable evidence about + the alternatives. +- Do not use an existing ECS name as a namespace. If the name must differ, use a + different namespace name to avoid clashes or avoid using the namespace + entirely. + [nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating +[otep222]: https://github.com/open-telemetry/oteps/pull/222 From 52c08605b7ef626906380a1aa718cb745192e28c Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Thu, 21 Sep 2023 17:18:27 +0200 Subject: [PATCH 02/10] Rename to 'soft recommendations' --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7940b68f74..d52a527a5f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -187,8 +187,8 @@ Conventions per [OTEP 222][otep222]. When adding a semantic convention that exists in some form in ECS, consider the following guidelines: - Prefer using the existing ECS name when possible. In particular: - - Do not amend ECS names to follow plural guidelines or other syntactical - attribute naming rules. + - Do not amend ECS names to follow plural guidelines or other soft + recommendations. - If proposing a name that differs from the ECS convention, provide usage data, user issue reports or feature requests or comparable evidence about the alternatives. From af694df1d0cf5228c16a7db8f787028ae9e1c5b4 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Mon, 25 Sep 2023 17:10:35 +0200 Subject: [PATCH 03/10] Fix markdownlint --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d52a527a5f..31ae87aff7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -187,7 +187,7 @@ Conventions per [OTEP 222][otep222]. When adding a semantic convention that exists in some form in ECS, consider the following guidelines: - Prefer using the existing ECS name when possible. In particular: - - Do not amend ECS names to follow plural guidelines or other soft + - Do not amend ECS names to follow plural guidelines or other soft recommendations. - If proposing a name that differs from the ECS convention, provide usage data, user issue reports or feature requests or comparable evidence about From 68709a068cb11d7ade031a7e8b4585c21f424808 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Thu, 5 Oct 2023 11:49:26 +0200 Subject: [PATCH 04/10] Explicitly add prior work on another standard as acceptable evidence --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4be05fdef2..f1d61e11ca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -190,8 +190,8 @@ exists in some form in ECS, consider the following guidelines: - Do not amend ECS names to follow plural guidelines or other soft recommendations. - If proposing a name that differs from the ECS convention, provide usage - data, user issue reports or feature requests or comparable evidence about - the alternatives. + data, user issue reports, feature requests, examples of prior work on a + different standard or comparable evidence about the alternatives. - Do not use an existing ECS name as a namespace. If the name must differ, use a different namespace name to avoid clashes or avoid using the namespace entirely. From e86a7f069fc03304488b7aa39addaa50ceccb34a Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Fri, 13 Oct 2023 11:31:33 +0200 Subject: [PATCH 05/10] Address feedback --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b157e3dc9..a16cdd0f08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -204,8 +204,8 @@ Conventions per [OTEP 222][otep222]. When adding a semantic convention that exists in some form in ECS, consider the following guidelines: - Prefer using the existing ECS name when possible. In particular: - - Do not amend ECS names to follow plural guidelines or other soft - recommendations. + - Do not modify an ECS name for the only reason of complying with + OpenTelemetry general attribute guidelines. - If proposing a name that differs from the ECS convention, provide usage data, user issue reports, feature requests, examples of prior work on a different standard or comparable evidence about the alternatives. From 331e7ca4f4aeb88339498fb3cc9418b8689576e1 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Fri, 13 Oct 2023 11:43:36 +0200 Subject: [PATCH 06/10] Linting --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e21e7808f..aa2a0fa3e1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -215,4 +215,4 @@ exists in some form in ECS, consider the following guidelines: [nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating [stability guarantees]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/versioning-and-stability.md#semantic-conventions-stability -[otep222]: https://github.com/open-telemetry/oteps/pull/222 \ No newline at end of file +[otep222]: https://github.com/open-telemetry/oteps/pull/222 From b7f14b14fdbc569d5ac7141004f839b0a14e783b Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Fri, 13 Oct 2023 14:51:35 +0200 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Alexander Wert --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa2a0fa3e1..8499ac244b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -205,7 +205,7 @@ exists in some form in ECS, consider the following guidelines: - Prefer using the existing ECS name when possible. In particular: - Do not modify an ECS name for the only reason of complying with - OpenTelemetry general attribute guidelines. + [OpenTelemetry general attribute naming guidelines](https://opentelemetry.io/docs/specs/otel/common/attribute-naming/). - If proposing a name that differs from the ECS convention, provide usage data, user issue reports, feature requests, examples of prior work on a different standard or comparable evidence about the alternatives. From 5b69fe2115fd52b43859ef7cba901e02d100b92c Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Wed, 29 Nov 2023 13:25:40 +0100 Subject: [PATCH 08/10] Address feedback --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c855cf2310..05abb73817 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -206,11 +206,12 @@ Conventions per [OTEP 222][otep222]. When adding a semantic convention that exists in some form in ECS, consider the following guidelines: - Prefer using the existing ECS name when possible. In particular: - - Do not modify an ECS name for the only reason of complying with - [OpenTelemetry general attribute naming guidelines](https://opentelemetry.io/docs/specs/otel/common/attribute-naming/). - If proposing a name that differs from the ECS convention, provide usage data, user issue reports, feature requests, examples of prior work on a different standard or comparable evidence about the alternatives. + - When no suitable alternatives are provided, altering an ECS name solely + for the purpose of complying with [Name Pluralization guidelines](https://opentelemetry.io/docs/specs/otel/common/attribute-naming/#name-pluralization-guidelines) + MAY BE avoided. - Do not use an existing ECS name as a namespace. If the name must differ, use a different namespace name to avoid clashes or avoid using the namespace entirely. From 383c2693f716a65dcf85f9795d6a074c2581a98e Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Wed, 29 Nov 2023 13:27:18 +0100 Subject: [PATCH 09/10] Make linter happy --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 05abb73817..2af4cbe1db 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -209,7 +209,7 @@ exists in some form in ECS, consider the following guidelines: - If proposing a name that differs from the ECS convention, provide usage data, user issue reports, feature requests, examples of prior work on a different standard or comparable evidence about the alternatives. - - When no suitable alternatives are provided, altering an ECS name solely + - When no suitable alternatives are provided, altering an ECS name solely for the purpose of complying with [Name Pluralization guidelines](https://opentelemetry.io/docs/specs/otel/common/attribute-naming/#name-pluralization-guidelines) MAY BE avoided. - Do not use an existing ECS name as a namespace. If the name must differ, use a From e34be16d99f823abe5eec99a7569f187d3e83eb5 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Mon, 11 Dec 2023 17:17:59 +0100 Subject: [PATCH 10/10] Apply suggestions from code review Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2af4cbe1db..0bfa90bc98 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -210,12 +210,13 @@ exists in some form in ECS, consider the following guidelines: data, user issue reports, feature requests, examples of prior work on a different standard or comparable evidence about the alternatives. - When no suitable alternatives are provided, altering an ECS name solely - for the purpose of complying with [Name Pluralization guidelines](https://opentelemetry.io/docs/specs/otel/common/attribute-naming/#name-pluralization-guidelines) + for the purpose of complying with [Name Pluralization guidelines](docs/general/attribute-naming.md#name-pluralization-guidelines) MAY BE avoided. - Do not use an existing ECS name as a namespace. If the name must differ, use a different namespace name to avoid clashes or avoid using the namespace - entirely. + entirely. See the [ECS field reference] for existing namespaces. [nvm]: https://github.com/nvm-sh/nvm/blob/master/README.md#installing-and-updating [stability guarantees]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.26.0/specification/versioning-and-stability.md#semantic-conventions-stability [otep222]: https://github.com/open-telemetry/oteps/pull/222 +[ECS field reference]: https://www.elastic.co/guide/en/ecs/current/ecs-field-reference.html