From fccfa7cf645b6ea920098fc821d0574181606436 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 20 Dec 2024 14:21:30 -0800 Subject: [PATCH 01/10] Add first version of semconv guidance --- CONTRIBUTING.md | 12 ++ .../how-to-define-semantic-conventions.md | 139 ++++++++++++++++++ 2 files changed, 151 insertions(+) create mode 100644 docs/general/how-to-define-semantic-conventions.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 111d35baa9..f8f7c07cd5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,6 +82,18 @@ and helps to keep conventions consistent and backward compatible. Want to define your own conventions outside this repo while building on OTel’s? Come help us [decentralize semantic conventions](https://github.com/open-telemetry/weaver/issues/215). +### Suggesting conventions for a new areas + +Defining semantic conventions involves a group of people who are familiar with the domain, +are involved into instrumentation efforts, and are committed to be the point of contact for +pull requests, issues, and questions in this area. + +Check out [project management](https://github.com/open-telemetry/community/blob/main/project-management.md) +for the details on how to start. + +Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) for +guidance. + ### Prerequisites The Specification uses several tools to check things like style, diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md new file mode 100644 index 0000000000..a39dcff2af --- /dev/null +++ b/docs/general/how-to-define-semantic-conventions.md @@ -0,0 +1,139 @@ + + +# How to define new semantic conventions + +**Status**: [Development][DocumentStatus] + + + + + +This document describes requirements, recommendations, and best practices on how to define conventions +for the new areas or make substantial changes to the existing ones. + +## Defining new conventions + +- New conventions MUST have a group of codeowners. See [project management](https://github.com/open-telemetry/community/blob/main/project-management.md) for more details. + +- New conventions SHOULD be defined in YAML files. See [YAML Model for Semantic Conventions](/model/README.md) for the details. +- New conventions SHOULD be defined with `development` stability level. +- New conventions SHOULD include attributes and telemetry signal definitions (spans, metrics, events, resources, profiles). + +### Best practices + +#### Defining attributes + +Reuse existing attributes when possible. Look through [existing conventions](/docs/attributes-registry/) for similar areas, +check out [common attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md). +Semantic conventions are encouraged to use attributes from different namespaces. + +Introduce new attributes when there is a clear use-case for them. Check if the most of the following applies: + +- you see a clear benefit for the end users to have it on their telemetry +- you're going to use this attribute on any spans, metrics, events, resources, or other telemetry signals +- you're going to use this attribute in instrumentations + +Postpone adding new attributes if it's not yet clear how beneficial having it on the telemetry is. + +When defining a new attribute + +- follow the [naming guidance](/docs/general/naming.md) +- make sure to provide descriptive `brief` and `note` - it should be clear what this attribute represents. + - If it represents some common concept documented externally, make sure to provide links. For example, + always provide links to attributes describing notions defined in RFCs or other standards. + - If attribute value is likely to contain PII or other sensitive information, make sure to capture it in the `note`. + + Include the following warning + ```yaml + - id: user.full_name + ... + note: | + ... + + > [!WARNING] + > + > This field contains sensitive (PII) information. + ``` +- use appropriate [attribute type](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md#type) + - If value has a reasonably short (open or closed) set of possible values, it should be an enum. + - If value is a timestamp, it should be recorded as a string in ISO 8601 format. + - If value is an array of primitives, use array type. Avoid recording arrays as a string + - Use template type to define attributes with variable name (only the last segment of the name is dynamic). It's + useful to record user-defined set of key=value pairs such as HTTP headers. + - Capture complex values as a set of flat attributes. +- new attributes should always be defined with `development` stability +- provide realistic examples +- Avoid defining attributes with potentially unbound values. For example, strings that are longer than 1KB + or arrays with more than a thousand elements. Such value should be recoded in log/event body instead. + +Consider the scope attribute should be applicable in and how it may evolve in the future + +- when defining an attribute for a narrow use-case, consider other possible use-cases. + For example, when defining system-specific attribute, check if other systems in this domain would need + a similar attribute in the future. + Or, when defining a boolean flag such as `foo.is_error`, consider if you can represent it, along with + additional details, in a more extensible way, for example, with `foo.status_code` attribute. + +- when defining a very broad attribute applicable to multiple domains or systems, check if there are + standards or common best practices in the industry to rely on. + Avoid defining generic attributes that are not grounded by some existing standard. + +> [!NOTE] +> +> When defining conventions for an area with multiple implementations or systems such as databases, identity providers, +> or cloud providers it takes some time to find the right balance between being overly generic vs not generic enough. +> +> It's essential to start with experimental conventions, document how these conventions apply to a diverse set +> of provides/systems/libraries, and prototype instrumentations. +> +> The end-user experience should be used as the main guiding principle: +> +> - if the attribute is expected to be used on general-purpose metrics for this area, +> consider introducing common attribute. +> +> For example, almost every messaging system has a notion of queue or topic. The +> queue or topic name is essential on latency or throughput metrics and equally +> important on spans to debug and visualize message flow. This is a good sign +> that we need a generic attribute that represents any type of messaging destination. +> +> - if the attribute represents something that would be useful in a narrow set of scenarios +> or only on a system-specific metrics/spans/events, it's usually a sign that this +> attribute does not need to be generic. + +#### Defining spans + +TBD + +#### Defining metrics + +TBD + +#### Defining resources + +TBD + +#### Defining events + +TBD + +## Stabilizing existing conventions + +- All conventions MUST be defined in YAML before they can be declared stable +- Conventions that are not used by instrumentations MUST NOT be declared stable + +TODO: +- prototyping/implementation requirements +- migration plan + +### Migration plan + +TODO + + + + + + From 447c2e68f63e034404a3901c9c56ac499f13e7f6 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 20 Dec 2024 14:24:57 -0800 Subject: [PATCH 02/10] toc --- CONTRIBUTING.md | 1 + docs/general/how-to-define-semantic-conventions.md | 10 ++++++++++ 2 files changed, 11 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8f7c07cd5..351d8255d8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,6 +14,7 @@ requirements and recommendations. - [Sign the CLA](#sign-the-cla) - [How to Contribute](#how-to-contribute) - [Which semantic conventions belong in this repo](#which-semantic-conventions-belong-in-this-repo) + - [Suggesting conventions for a new areas](#suggesting-conventions-for-a-new-areas) - [Prerequisites](#prerequisites) - [1. Modify the YAML model](#1-modify-the-yaml-model) - [Code structure](#code-structure) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index a39dcff2af..af520d38a8 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -9,6 +9,16 @@ aliases: [how-to-define-new-semantic-conventions] +- [Defining new conventions](#defining-new-conventions) + - [Best practices](#best-practices) + - [Defining attributes](#defining-attributes) + - [Defining spans](#defining-spans) + - [Defining metrics](#defining-metrics) + - [Defining resources](#defining-resources) + - [Defining events](#defining-events) +- [Stabilizing existing conventions](#stabilizing-existing-conventions) + - [Migration plan](#migration-plan) + This document describes requirements, recommendations, and best practices on how to define conventions From e41fd0da30409b737f22827bd85634dbb5ce86d0 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 20 Dec 2024 14:26:08 -0800 Subject: [PATCH 03/10] up --- docs/general/how-to-define-semantic-conventions.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index af520d38a8..0395913c88 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -141,9 +141,3 @@ TODO: ### Migration plan TODO - - - - - - From 152fa7a215daa3fe4851b7f03b5975a6cc059aab Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 20 Dec 2024 14:46:51 -0800 Subject: [PATCH 04/10] clean up --- .../how-to-define-semantic-conventions.md | 108 +++++++++--------- 1 file changed, 56 insertions(+), 52 deletions(-) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index 0395913c88..a62e2004f0 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -30,7 +30,7 @@ for the new areas or make substantial changes to the existing ones. - New conventions SHOULD be defined in YAML files. See [YAML Model for Semantic Conventions](/model/README.md) for the details. - New conventions SHOULD be defined with `development` stability level. -- New conventions SHOULD include attributes and telemetry signal definitions (spans, metrics, events, resources, profiles). +- New conventions SHOULD include telemetry signal definitions (spans, metrics, events, resources, profiles) and MAY include new attribute definitions. ### Best practices @@ -38,25 +38,28 @@ for the new areas or make substantial changes to the existing ones. Reuse existing attributes when possible. Look through [existing conventions](/docs/attributes-registry/) for similar areas, check out [common attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md). -Semantic conventions are encouraged to use attributes from different namespaces. +Semantic conventions authors are encouraged to use attributes from different namespaces. -Introduce new attributes when there is a clear use-case for them. Check if the most of the following applies: +Introduce new attributes when there is a clear use-case for them. Consider adding +them if most of the following apply: -- you see a clear benefit for the end users to have it on their telemetry -- you're going to use this attribute on any spans, metrics, events, resources, or other telemetry signals -- you're going to use this attribute in instrumentations +- They provide a clear benefit to end users by enhancing telemetry. +- You plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. +- The attribute will be utilized in instrumentations. -Postpone adding new attributes if it's not yet clear how beneficial having it on the telemetry is. +Postpone adding new attributes if their benefit to telemetry is not yet clear. -When defining a new attribute +When defining a new attribute: -- follow the [naming guidance](/docs/general/naming.md) -- make sure to provide descriptive `brief` and `note` - it should be clear what this attribute represents. - - If it represents some common concept documented externally, make sure to provide links. For example, - always provide links to attributes describing notions defined in RFCs or other standards. - - If attribute value is likely to contain PII or other sensitive information, make sure to capture it in the `note`. +- Follow the [naming guidance](/docs/general/naming.md) +- Provide descriptive `brief` and `note` sections to clearly explain what the attribute represents. + - If the attribute represents a common concept documented externally, include relevant links. + For example, always link to attributes related to concepts defined in RFCs or other standards. + - If the attribute's value might contain PII or other sensitive information, explicitly call this out in + the `note`. + + Include a warning similar to the following: - Include the following warning ```yaml - id: user.full_name ... @@ -65,53 +68,54 @@ When defining a new attribute > [!WARNING] > - > This field contains sensitive (PII) information. + > This attribute contains sensitive (PII) information. ``` -- use appropriate [attribute type](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md#type) - - If value has a reasonably short (open or closed) set of possible values, it should be an enum. - - If value is a timestamp, it should be recorded as a string in ISO 8601 format. - - If value is an array of primitives, use array type. Avoid recording arrays as a string - - Use template type to define attributes with variable name (only the last segment of the name is dynamic). It's - useful to record user-defined set of key=value pairs such as HTTP headers. - - Capture complex values as a set of flat attributes. -- new attributes should always be defined with `development` stability -- provide realistic examples -- Avoid defining attributes with potentially unbound values. For example, strings that are longer than 1KB - or arrays with more than a thousand elements. Such value should be recoded in log/event body instead. - -Consider the scope attribute should be applicable in and how it may evolve in the future - -- when defining an attribute for a narrow use-case, consider other possible use-cases. - For example, when defining system-specific attribute, check if other systems in this domain would need - a similar attribute in the future. - Or, when defining a boolean flag such as `foo.is_error`, consider if you can represent it, along with - additional details, in a more extensible way, for example, with `foo.status_code` attribute. - -- when defining a very broad attribute applicable to multiple domains or systems, check if there are - standards or common best practices in the industry to rely on. - Avoid defining generic attributes that are not grounded by some existing standard. +- Use the appropriate [attribute type](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md#type) + - If the value has a reasonably short (open or closed) set of possible values, define it as an enum. + - If the value is a timestamp, record it as a string in ISO 8601 format. + - For arrays of primitives, use the array type. Avoid recording arrays as a single string. + - Use the template type to define attributes with variable names (only the last segment of the name should be dynamic). + This is useful for capturing user-defined key-value pairs, such as HTTP headers. + - Represent complex values as a set of flat attributes. +- Define new attributes with `development` stability. +- Provide realistic examples +- Avoid defining attributes with potentially unbounded values, such as strings longer than + 1 KB or arrays with more than 1,000 elements. Such values should be recorded in the log or event body instead. + +Consider the scope of the attribute and how it may evolve in the future: + +- When defining an attribute for a narrow use case, think about potential broader use cases. + For example, if creating a system-specific attribute, evaluate whether other systems + in the same domain might need a similar attribute in the future. + + Similarly, instead of defining a simple boolean flag like `foo.is_error`, consider a + more extensible approach, such as using a `foo.status_code` attribute to include additional details. + +- When defining a broad attribute applicable across multiple domains or systems, + check for existing standards or widely accepted best practices in the industry. + Avoid creating generic attributes that are not based on established standards. > [!NOTE] > -> When defining conventions for an area with multiple implementations or systems such as databases, identity providers, -> or cloud providers it takes some time to find the right balance between being overly generic vs not generic enough. +> When defining conventions for areas with multiple implementations or systems — such as databases, +> or cloud providers — it can take time to strike the right balance between being +> overly generic and not generic enough. > -> It's essential to start with experimental conventions, document how these conventions apply to a diverse set -> of provides/systems/libraries, and prototype instrumentations. +> Start with experimental conventions, document how they apply to a diverse range +> of providers, systems, or libraries, and prototype instrumentations. > -> The end-user experience should be used as the main guiding principle: +> The end-user experience should serve as the primary guiding principle: > -> - if the attribute is expected to be used on general-purpose metrics for this area, -> consider introducing common attribute. +> - If the attribute is expected to be used in general-purpose metrics for the area, +> consider introducing a common attribute. > -> For example, almost every messaging system has a notion of queue or topic. The -> queue or topic name is essential on latency or throughput metrics and equally -> important on spans to debug and visualize message flow. This is a good sign -> that we need a generic attribute that represents any type of messaging destination. +> For example, most messaging systems have a concept like a queue or topic. +> Queue or topic names are critical for latency and throughput metrics and +> equally important for spans to debug and visualize message flow. +> This indicates the need for a generic attribute representing any type of messaging destination. > -> - if the attribute represents something that would be useful in a narrow set of scenarios -> or only on a system-specific metrics/spans/events, it's usually a sign that this -> attribute does not need to be generic. +> - If the attribute represents something useful in a narrow set of scenarios or +> is specific to certain system metrics, spans, or events, it likely does not need to be generic. #### Defining spans From a86b248ec4b6af15d6a113ca5ef1beeed2e31956 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 20 Dec 2024 15:09:23 -0800 Subject: [PATCH 05/10] lint --- docs/general/how-to-define-semantic-conventions.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index a62e2004f0..44f49309a6 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -37,7 +37,7 @@ for the new areas or make substantial changes to the existing ones. #### Defining attributes Reuse existing attributes when possible. Look through [existing conventions](/docs/attributes-registry/) for similar areas, -check out [common attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md). +check out [common attributes](/docs/general/attributes.md). Semantic conventions authors are encouraged to use attributes from different namespaces. Introduce new attributes when there is a clear use-case for them. Consider adding @@ -70,6 +70,7 @@ When defining a new attribute: > > This attribute contains sensitive (PII) information. ``` + - Use the appropriate [attribute type](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md#type) - If the value has a reasonably short (open or closed) set of possible values, define it as an enum. - If the value is a timestamp, record it as a string in ISO 8601 format. @@ -139,9 +140,12 @@ TBD - Conventions that are not used by instrumentations MUST NOT be declared stable TODO: + - prototyping/implementation requirements - migration plan ### Migration plan TODO + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From 993aca56ddb062d87949b110b451cfa139086073 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 27 Dec 2024 14:31:15 -0800 Subject: [PATCH 06/10] feedback: part1 --- CONTRIBUTING.md | 6 +++--- docs/general/how-to-define-semantic-conventions.md | 14 +++++++------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 351d8255d8..c9fa6f5ba3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,14 +86,14 @@ Come help us [decentralize semantic conventions](https://github.com/open-telemet ### Suggesting conventions for a new areas Defining semantic conventions involves a group of people who are familiar with the domain, -are involved into instrumentation efforts, and are committed to be the point of contact for +are involved with instrumentation efforts, and are committed to be the point of contact for pull requests, issues, and questions in this area. Check out [project management](https://github.com/open-telemetry/community/blob/main/project-management.md) for the details on how to start. -Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) for -guidance. +Refer to the [How to define new conventions](/docs/general/how-to-define-semantic-conventions.md) +document for guidance. ### Prerequisites diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index 44f49309a6..4419132eb5 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -22,7 +22,7 @@ aliases: [how-to-define-new-semantic-conventions] This document describes requirements, recommendations, and best practices on how to define conventions -for the new areas or make substantial changes to the existing ones. +for new areas or make substantial changes to the existing ones. ## Defining new conventions @@ -40,14 +40,14 @@ Reuse existing attributes when possible. Look through [existing conventions](/do check out [common attributes](/docs/general/attributes.md). Semantic conventions authors are encouraged to use attributes from different namespaces. -Introduce new attributes when there is a clear use-case for them. Consider adding -them if most of the following apply: +Consider adding a new attribute when the following apply: -- They provide a clear benefit to end users by enhancing telemetry. -- You plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. -- The attribute will be utilized in instrumentations. +- It provides a clear benefit to end users by enhancing telemetry. +- There is a clear plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. +- There is a clear plan on how these attributes will be used by instrumentations -Postpone adding new attributes if their benefit to telemetry is not yet clear. +Semantic convention maintainers may reject the addition of a new attribute if its benefits +and use-cases are not yet clear. When defining a new attribute: From e599d0f0ab3a9003bc202f78d4c58689b57bc941 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 27 Dec 2024 14:48:20 -0800 Subject: [PATCH 07/10] feedback: part2 --- docs/general/how-to-define-semantic-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index 4419132eb5..9bebe708d8 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -43,7 +43,7 @@ Semantic conventions authors are encouraged to use attributes from different nam Consider adding a new attribute when the following apply: - It provides a clear benefit to end users by enhancing telemetry. -- There is a clear plan to use the attribute in spans, metrics, events, resources, or other telemetry signals. +- There is a clear plan to use the attributes when defining spans, metrics, events, resources, or other telemetry signals in semantic conventions. - There is a clear plan on how these attributes will be used by instrumentations Semantic convention maintainers may reject the addition of a new attribute if its benefits From ea9cdda318960b6f4857f0356af3b4e59f90c115 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 2 Jan 2025 17:25:10 -0800 Subject: [PATCH 08/10] feedback --- docs/general/how-to-define-semantic-conventions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index 9bebe708d8..caed54ea51 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -40,7 +40,7 @@ Reuse existing attributes when possible. Look through [existing conventions](/do check out [common attributes](/docs/general/attributes.md). Semantic conventions authors are encouraged to use attributes from different namespaces. -Consider adding a new attribute when the following apply: +Consider adding a new attribute if all of the following apply: - It provides a clear benefit to end users by enhancing telemetry. - There is a clear plan to use the attributes when defining spans, metrics, events, resources, or other telemetry signals in semantic conventions. From d3da1468b648b8f1284cb377d1ffa405ec173574 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 10 Jan 2025 19:37:34 -0800 Subject: [PATCH 09/10] Apply suggestions from code review Co-authored-by: Trask Stalnaker --- CONTRIBUTING.md | 4 ++-- docs/general/how-to-define-semantic-conventions.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c9fa6f5ba3..7acf6bd72a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -83,9 +83,9 @@ and helps to keep conventions consistent and backward compatible. Want to define your own conventions outside this repo while building on OTel’s? Come help us [decentralize semantic conventions](https://github.com/open-telemetry/weaver/issues/215). -### Suggesting conventions for a new areas +### Suggesting conventions for a new area -Defining semantic conventions involves a group of people who are familiar with the domain, +Defining semantic conventions requires a group of people who are familiar with the domain, are involved with instrumentation efforts, and are committed to be the point of contact for pull requests, issues, and questions in this area. diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index caed54ea51..cc5f2e3389 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -54,7 +54,7 @@ When defining a new attribute: - Follow the [naming guidance](/docs/general/naming.md) - Provide descriptive `brief` and `note` sections to clearly explain what the attribute represents. - If the attribute represents a common concept documented externally, include relevant links. - For example, always link to attributes related to concepts defined in RFCs or other standards. + For example, always link to concepts defined in RFCs or other standards. - If the attribute's value might contain PII or other sensitive information, explicitly call this out in the `note`. @@ -75,7 +75,7 @@ When defining a new attribute: - If the value has a reasonably short (open or closed) set of possible values, define it as an enum. - If the value is a timestamp, record it as a string in ISO 8601 format. - For arrays of primitives, use the array type. Avoid recording arrays as a single string. - - Use the template type to define attributes with variable names (only the last segment of the name should be dynamic). + - Use the template type to define attributes with dynamic names (only the last segment of the name should be dynamic). This is useful for capturing user-defined key-value pairs, such as HTTP headers. - Represent complex values as a set of flat attributes. - Define new attributes with `development` stability. From d09cce343377962be7d6afe72d71d39081df3630 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 10 Jan 2025 19:52:01 -0800 Subject: [PATCH 10/10] feedback --- CONTRIBUTING.md | 2 +- docs/general/how-to-define-semantic-conventions.md | 6 +++++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7acf6bd72a..1a84dbfca9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ requirements and recommendations. - [Sign the CLA](#sign-the-cla) - [How to Contribute](#how-to-contribute) - [Which semantic conventions belong in this repo](#which-semantic-conventions-belong-in-this-repo) - - [Suggesting conventions for a new areas](#suggesting-conventions-for-a-new-areas) + - [Suggesting conventions for a new area](#suggesting-conventions-for-a-new-area) - [Prerequisites](#prerequisites) - [1. Modify the YAML model](#1-modify-the-yaml-model) - [Code structure](#code-structure) diff --git a/docs/general/how-to-define-semantic-conventions.md b/docs/general/how-to-define-semantic-conventions.md index cc5f2e3389..dad4e90b74 100644 --- a/docs/general/how-to-define-semantic-conventions.md +++ b/docs/general/how-to-define-semantic-conventions.md @@ -34,6 +34,10 @@ for new areas or make substantial changes to the existing ones. ### Best practices +> [!NOTE] +> +> This section contains non-normative guidance. + #### Defining attributes Reuse existing attributes when possible. Look through [existing conventions](/docs/attributes-registry/) for similar areas, @@ -89,7 +93,7 @@ Consider the scope of the attribute and how it may evolve in the future: For example, if creating a system-specific attribute, evaluate whether other systems in the same domain might need a similar attribute in the future. - Similarly, instead of defining a simple boolean flag like `foo.is_error`, consider a + Similarly, instead of defining a simple boolean flag indicating a success or failure, consider a more extensible approach, such as using a `foo.status_code` attribute to include additional details. - When defining a broad attribute applicable across multiple domains or systems,